Do all the things like ++ or -- rants, post your own rants, comment on others' rants and build your customized dev avatarSign Up
hatemyjob11011dI suggest you look at microsoft docs for c#, or the docker docs, or the unity tutorial docs. I think these are nicely structured and progress smoothly in taking a user from 0 to X.
Fast-Nop2200011dDocument what each feature does. Stick to the principle of the least surprise - but clearly document gotchas where they are unavoidable.
Supply a demo project where stuff can be seen in action. The jump from a feature list to "how do I use that stuff for real" is often huge - especially if the UI is misdesigned (looking at you, Git).
For the tech docs, the number 1 thing that most OSS projects are missing is some sort of architectural overview. Some top level diagrams how things go together.
So there are several things questions I think your docs should answer:
What does the project do?
What problem does it solve?
How do try it out?
How do install it in production?
Docs for functions:
Use common names for things, ( think about how people search docs usong ctrl+ f , so what keywords would they use? Authentication, authorization, login etc should all be linked to the same place ( if they are indeed the same)
Make sure the docs mention them.
Think about at least three ways people browse your docs: searching for the correct arguments for a function, how to install the project and "I've got an issue and I don't know what's wrong or how to fix it.
@hatemyjob @Fast-Nop @heyheni @Charmgoggles thank you guys for tips, hope to make use of them.
Anyway, that wasn’t exactly what I was asking. My concern is to keep docs up to date if sth in code changes, for example, I change configuration option from ‘title’ to ‘name’, how do I make sure I don’t forget to update option also in docs?
I use tools that keep the documentation next to the code. Some of the tools also warn if the arguments differ from the code. In pycharm this works really well.
But for the readme that doesn't work, unless you compile the readme with the actual code.