5 ms·
I've found that the higher-level docs often don't even need to be writing per se. I'd stick things like the 3-5 minute overview video, 30-60 minute presentation
by mr_tristan 5y ago
I've found that the higher-level docs often don't even need to be writing per se. I'd stick things like the 3-5 minute overview video, 30-60 minute presentations, and code examples in this type of category.
Who maintains these? Most development teams I've met never bother checking the example code works. 99% of the time, they'll write up a presentation, once, click "record" on the video conferencing software, and everyone says "cool, it's documented". And then, 6 months later, half the presentation is obsolete, and it ends up being even more confusing because as the reader, you have to investigate what has changed since this presentation happened.
I've noticed, if you put some real thought behind maintaining these higher level docs, you don't end up with _tons_ of documentation. And the speed of adoption is rapid. But it takes design, a feedback loop, etc. It's really another kind of deliverable, separate from creating a software product itself.
- cratermoon 5y ago> don't even need to be writing per se It's best to have documentation in a variety of communication formats. I cannot learn by watching a video as well as I can by reading, but everyone is different. If the only, or primary, documentation for your product or code is a video, I'm likely to pass on it unless there are no other choices.
- SomeHacker44 5y agoExtraordinarily strongly disagree. Documentation should be first, best, and most thorough in written form. It is easily searchable, easily transferred, easily scanned for relevant sections. Do anything else you want for your audienc3, but for me personally if there is not textual documentation, I will consider your system, software, library or whatever effectively undocumented.
- astrange 5y agoYou can't rely on documentation to be correct because, like comments, it can't be tested or automatically updated. It's only going to be reliable if the system under it never changes.
- mr_tristan 5y agoI didn't say documentation shouldn't be written; writing is just one of many media types. Many people do not stay focused with longer formats in writing. So adopting a variety of media is a good idea, especially for the fuzzier "conceptual" documents, as opposed to reference documentation. And I say this as someone who prefers books. I've made the mistake of only using writing, and noticed about half of the team just never seemed to grasp the concepts. Example projects with really short videos helped them a lot.