News for hackers. Stuff that matters.

A comment on The Elephant at WWDC. Parent comment

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.

[ Parent | on HN ]
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.

[ Parent | on HN ]
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.
[ Parent | on HN ]