Advanced versioned docs

[NikitaIT]

Below will describe several proposals, the implementation of which may be very useful.

Version diff

Documentation is always built as a knowledge base that records changes over time. The closest of these systems is git.
Now versioning is limited to creating version snapshots.

For example: https://github.com/facebook/docusaurus/tree/master/website/versioned_docs

This can be done automatically, just like git does. In fact there are several branches for versions and most of the branches are increments of previous ones. This will make it easier to review changes and can even be used to semi-automatically generate a migration guide.

Trellis - app with git-like sidebar. Yes, of course this is a slightly different area, but looking at changes between versions like this is what we do when we write a migration guide.

Version visual diff

On the other hand, documentation is a graph of related documents and concepts, changes in which can be conveniently presented and visualized using graph rewriting and the TGG formalism.

Yes, of course the tools for this are not very developed and convenient, but one day they will become convenient. Progy for exemple.

Here is one example of TGG:

Quick visual review

Also, when exploring libraries, you often need a quick review. One of the most convenient ways to do this so far is to build a graph, as in Obsidian:

Documentation implies discussions

Also, the documentation implies discussions tied to it. This is one of the most important things in open source projects, we often want to discuss how the api should look, but we also want the discussion to be tracked over time. And consistent with the written document.

Glossary

The glossary of terms should be not only for the search. This is the foundation of domain driven design, and documentation is the main way to understand the domain that the library is working with.

For example: https://effector.now.sh/docs/glossary

For discussion

The combination of these four things is the future of all developing products docs.

It is important that there are actually many products like Notion for documentation, but they focus on co-editing and other technical things, which is why they are not domain oriented enough.

It would be nice to collect more examples.

I also want to point out that all these examples can work for statically generated documentation.

[NikitaIT]

Probably the most advanced now is the gitbook. However, it is also far from perfect. I think docusaurus can be a project that takes into account all requirements and best practices.

[NikitaIT]

I also see that linking by editUrl can be improved based on git integration and fs mapping.