|
This view is too much simplified. If docs were tree vs graph problem we would probably have at least some orgs doing it right, while there are literarily almost zero. Just few of the missing aspects: 1. Narrative style. You can't do ad hoc whatever wherever and call it a day. Most people don't have it and many are quite illiterate IMO. You need to practice this and most engineers don't like that. Hell, even most seniors don't like writing tickets IME which take almost the same time as putting garbage on Slack. I created templates on both GH and GL and almost nobody uses them even tho you don't need to think about anything but follow few rules. 2. Its quite hard to know what level of detail to put in documentation. You need a lot of experience for this - put to much, and it gets quickly outdated, put too little, and it doesn't convey much. Good documentation exists on multiple levels - as bunch of markup files "on the spot", as formal hi and low level documentation and also those are usually affecting different target groups so you actually need to design docs. Cross references are absolutely essential, the docs need to be 100% hyperlinked and in static site format (no big Word or PDF docs really, that should exist only as an export variant). But you also need a tree, because you can just say to people "here is a bunch of docs" just surf around, and good luck". So both tree and graph are required at the same time. 3. Documentation is a service. It has source code, build procedure, automatic link checking, versions, exports to bunch of formats, crosslinks, variables, macros, configuration for different environments, abbreviations, definitions, automation, includes and what not... Its quite hard to get it right. After years of struggle on different projects I finally created my own stuff [1] by bundling many different tools and configs in docker container that I use on all projects, for docs spanning 50-500 pages. I maintain that for years now, constantly (so yeah, its a job). I am always interested in this as I write tones of docs as a part of system design role. If you have some good ideas to offer, don't hesitate. [1]: https://github.com/majkinetor/mm-docs-template |