Diátaxis as a documentation north star

[erlend-aasland]

The canopen docs start off with the following note:

Most of the documentation here is directly stolen from the CANopen Wikipedia page.

This documentation is a work in progress. Feedback and revisions are most welcome!

I suggest establishing a documentation north star. Having a guideline makes it easier to contribute, easier to review, and it makes for better docs :)

The nice thing is that someone already did the job of thinking out and writing down a set of pretty generic rules and expectations: Diátaxis (diataxis.fr)
And the best thing is that it's not a rigid set of rules, and you don't need to know everything about it in order to start applying it to your docs.

I suggest you take a short look at it; their website is a short and nice read, and even if you do decide to reject it, I believe you'll find a lot of valuable tips there. Several projects (Django being a nice example) have successfully applied Diátaxis to their docs.

If you do decide to adapt it, the good news is that the work can start right away. Diátaxis does not need a grand plan, nor does it recommend having one. To quote the Applying Diátaxis page:

Diátaxis is primarily intended as a pragmatic approach for people working on documentation. Most of the key principles required to put it into practice successfully can be grasped intuitively.

Don’t wait to understand Diátaxis before you start trying to put it into practice. Not only do you not need to understand it all to make use of it, you will not understand it until you have started using it (this itself is a Diátaxis principle).

As soon as you feel you have picked up an idea that seems worth applying to your work, try applying it. Come back here when you need more clarity or reassurance. Iterate between your work and reflecting on your work.