3 ms·
Very simply, you need at least one person to play curator. The curator maintains/publishes builds of the documentation and keeps everyone on task for docs. Even
by kodablah 9y ago
Very simply, you need at least one person to play curator. The curator maintains/publishes builds of the documentation and keeps everyone on task for docs. Even in medium-sized groups curation is not a full time job (usually this is a senior dev anyways, and they always have other stuff to do). The curator does not have to write everything, but they show up in the code reviews ask others for their docs and makes sure they are collated in a well structured and organized form.
Some other things I've learned... Wiki's suck, they become stale, they are disorganized, very informal. I recommend just keeping big ass user guides (can be different ones for different systems or even user guides about procedures that are not about products) using a well-organized documentation system and a well-kept table of contents. Don't waste tech writers on internal docs. They'll spend half their time asking the dev anyways, it will get stale, and asking a dev to write something is not asking too much. Keep the docs close to the code, but not in the code like comments. Docs close to the code can let people have less friction between code and doc commits. Each non-trivial repo should have a manual (a.k.a. user guide) anyways. And if you have to, say, grab a bunch of RST files from a few disparate Sphinx doc locations, so be it.
I personally use documentation as a point of pride. My favorite part of any project is documenting the awesomeness I did. I just make sure I order it in a reasonable order and don't bloviate.