3 ms·
I've worked at high-documentation companies and low-documentation companies. Documentation is hard to create and hard to maintain. It is essentially a simulati
by vonnik 4y ago
I've worked at high-documentation companies and low-documentation companies.
Documentation is hard to create and hard to maintain. It is essentially a simulation of an underlying reality, and that underlying reality *always* changes faster than the documentation can. So the documentation ends up being spotty, except for the parts that you find a way to automate. It's hard to automate all documentation, since so much knowledge is trapped in the analog world, and in peoples' minds.
Companies like storytell.ai are trying to solve the problem of creating documentation and written artifacts automatically out of Zoom recordings, etc. Others, like WeRice, are trying to create it out of videos of maintenance work done on equipment in the wild. I respect both efforts a lot. It's a hard problem to tackle.
* https://www.storytell.ai/ https://www.storytell.ai/
* https://we-rice.com/ https://we-rice.com/
- pessimizer 4y ago> It is essentially a simulation of an underlying reality, and that underlying reality always changes faster than the documentation can. That probably depends on how you prioritize it. You can dictate that the docs (and the tests) be written before features are added.
- Nevermark 4y agoThis can be improved with two sets of links for each doc. A set of manually added links to previous related material, with optional note. New links can be added by anyone. And a set of automatically generated reverse links, to documents that referenced the one being viewed. Both kinds of links help create continuity and context.
- vonnik 4y agoAgain, that a lot of extra work, and the automatic reverse links are v tooling dependent. You don't get them with Confluence or gDocs, fwiw. Nor do these suggestions solve the problem of doc creation. What many people ignore in these discussions is the real tradeoff between "time spent in meetings with people who can answer questions" vs "time spent by non-professional writers trying to be clear for strangers".