while thinking about 2.0, something occurred to me:
Where do we want to put our documentation? Currently everything resides in the main repo as until a few months ago there really was only one. Now we have at least two repos and possibly more in the future, which require some documentation, it seems to me we should think about how we do documenatation in the future.
Where do all Repos keep their documentation? How is it put together?
a. Keep everything in the hedgedoc/hedgedoc repo
This would make it easy to keep everything put together at all times, but necessitates multiple PRs to change a feature and update it’s documentation, which in general is not very desirable as stuff can come out of sync or even be forgotten.
b. Keep documentation in a separate hedgedoc/docs repo
This seems to be not much different than a as it has the same problems, but instead of nearly all repos, all repos have the “our documentation is in another castle” problem.
c. Keep specific documentation in the corresponding repos. Add general guides and multi-repo documentation to a hedgedoc/docs repo
This seems to be most desirable as everything is in the correct place generally speaking. Of course we would need to have extra PRs to change the API spec and such if they live in a separate docs repo, but that would be the case in a or b too and e.g API changes need to be addressed in multiple repos anyhow. This leaves the question where such documentation should be presented?
One place I thought of was readthedocs.org. I think we could use them to gather our documentation (multiple repos seem to be supported via subprojects) and make it a more pleasant experience to read them. Also multiple versions of documentation are suppored, which we should take advantage of not only for 2.0 and 2.1, but 1.7 as well. This make the old documentation accessible to people, when we switch to 2.0.
Improve the documentation
I think it would be great to improve the documentation for 2.0 (not sure it’ll help to much for 1.7 nor if we have enough man power to do that in addition to 2.0).
Some months ago @sheogorath mentioned this talk by Daniele Procida at PyCon Australia 2017 in the chat. There is also this blog post and the Django documentation as an example. The structure they propose is shown in this graphic:
Guides to get you started step-by-step
- learning by doing
- getting started
- inspiring confidence
- immediate sense of achievement
- concreteness, not abstraction
- minimum necessary explanation
- no distractions
- needs to be bulletproof. Anyone should be able to complete these
Guides to solve one specific problem
- a series of steps
- a focus on the goal
- addressing a specific question e.g “How to setup LDAP-Auth”
- no unnecessary explanation
- a little flexibility
- practical usability
- good naming
- giving context
- explaining why
- multiple examples, alternative approaches
- marking connections
- no instruction or technical description
descriptions of classes, APIs and such
I propose to structure our documentation in this way.
What do you think?