News for hackers. Stuff that matters.
Re:The Elephant at WWDC by mr_tristan on Sunday June 13, 2021 @11:13AM (#27493285)
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.

Re:The Elephant at WWDC by cratermoon on Sunday June 13, 2021 @11:19AM (#27493318)
> 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.

Re:The Elephant at WWDC by SomeHacker44 on Sunday June 13, 2021 @11:53AM (#27493599)
Extraordinarily 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.

Re:The Elephant at WWDC by mr_tristan on Sunday June 13, 2021 @08:26PM (#27497985)
I 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.

Re:The Elephant at WWDC by astrange on Sunday June 13, 2021 @06:19PM (#27497078)
You 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.