[HN Gopher] Making world-class docs takes effort
___________________________________________________________________
Making world-class docs takes effort
Author : todsacerdoti
Score : 80 points
Date : 2021-09-04 12:02 UTC (2 days ago)
(HTM) web link (daniel.haxx.se)
(TXT) w3m dump (daniel.haxx.se)
| simonw wrote:
| I love the description here of the "scanner" scripts that run to
| ensure that everything is documented, and each documentation
| section includes an example.
|
| I've been using a similar approach for my projects for a few
| years now and it's worked really well: I call it "Documentation
| unit tests": https://simonwillison.net/2018/Jul/28/documentation-
| unit-tes...
| kottaram wrote:
| Making anything world class takes effort. /s
| kaycebasques wrote:
| Wholeheartedly agree with the "your docs features examples"
| principle. For code/APIs there's really two categories of
| examples: A) minimal, viable, complete snippets that capture a
| use case [1] and B) end-to-end working example of core use cases
| tied together.
|
| The tricky thing about A is actually figuring out the common use
| cases and then finding the phrasing that your users would say. I
| was lucky when I worked on the Chrome DevTools docs because I had
| a huge record of the problems that people actually faced and how
| they described them: all the google-chrome-devtools questions [2]
| on Stack Overflow. For smaller products where obviously you won't
| have an active Stack Oveflow community, a good source of insight
| is support tickets.
|
| [1] https://stackoverflow.com/help/minimal-reproducible-example
|
| [2]: https://stackoverflow.com/questions/tagged/google-chrome-
| dev...
| fogof wrote:
| > Your docs is not extracted from code
|
| I don't really understand this. If the documentation doesn't
| exist next to the code it documents, isn't there a risk that
| someone will change the code without updating the docs, leading
| to confusing or wrong docs?
| ghoward wrote:
| Once again, Daniel has great points. I would just like to add a
| few:
|
| * When documenting API's, make sure to document preconditions and
| postconditions, as well an invariants.
|
| * Make sure to document guarantees and non-guarantees. Guarantees
| are things the code must or must not do, where non-guarantees are
| things that give the code wiggle room and which users cannot rely
| on, even if they begin to, a la https://xkcd.com/1172/.
|
| * Make sure docs can be tested, just like code. Daniel actually
| does this for curl docs (later in the post), but he does not list
| it as a standard. I think it's a great way to help keep docs up
| to a high standard.
| eddieh wrote:
| _> Your docs belong in the code repository_
|
| This is essential. If developers have to hunt down the
| documentation it will never be updated. It needs to be generated
| from plain text files in the _same_ repository.
|
| Way to many times have I encountered documentation fragmented and
| outdated split between Confluence, Google Docs, Google Sites,
| GitHub wikis, network shares, Dropbox, Google Drive, separate git
| repositories, and other such abominations (MS SharePoint).
|
| Treat you docs like code, treat it like it's important, it is the
| least you can do to even have a chance of producing marginally
| acceptable documentation, let alone good documentation.
| simonw wrote:
| Absolutely agree. The documentation relating to the code needs
| to live with that code.
|
| The single biggest problem I see with documentation is lack of
| trust: if people in an organization learn that the
| documentation is often out-of-date they will stop consulting
| it, which means the will also stop writing it.
|
| The fix for this is for the documentation to live alongside the
| code, and for code reviews to take that into account: if an
| implementation change leaves the documentation out-of-date,
| point that out in the code review and refuse to merge it until
| the documentation has been updated as part of the same change!
| throwaway984393 wrote:
| I have managed a lot of code, a lot of projects/products, and a
| lot of documentation. Code is code. Documentation is not code.
| The more you try to force Documentation to be Code, the worse
| it is as Documentation; the more you force Code to be like
| Documentation, the worse it is as either.
|
| First, consider their purposes.
|
| Code is designed to be a set of instructions. It is designed to
| tell a computer what to do. It is a loosely structured, line-
| by-line organization of text.
|
| Documentation is designed to explain to human beings how and
| why something does or doesn't work. It is designed to give
| humans deep knowledge about a subject. It is an array of media
| and document types, structures, and features designed to
| facilitate humans composing and presenting information in an
| optimal way for humans to understand.
|
| Next, consider their usage.
|
| Code is designed to be interacted with via version-control
| system, used by build tools, in order to generate programs. Its
| access is highly controlled and often requires skilled labor.
| It is updated through a highly structured lifecycle.
|
| Documentation is designed to be interacted with by humans in a
| web browser or rich text editor in order to find, compose, and
| publish complex documents. It is designed to be accessible by
| all users, easily and frequently updated, by people who are not
| technical writers. It is updated in small pieces by anyone at
| any time without much regard, because almost any change is an
| improvement that does not require great scrutiny or validation.
|
| At the end of the day, developers just don't know how to make
| good docs. They think GitHub makes a good place for docs, when
| it's actually incredibly painful to create and maintain docs
| there for any reasonable human that needs more than a plain-
| text file maintained via an arduous SDLC or overly-complicated
| automated program. In fact, real documentation requires a
| system designed _for documentation_ , such as Confluence or
| another Wiki, that has a WYSIWYG editor, mixed media, and
| enough editing controls to compose a rich-text document that
| can express complex ideas in minimal space using a variety of
| presentation methods.
|
| Markdown files are the perfect example of why Documentation is
| quite complicated to make. Markdown has only a small number of
| formatting features, and anything past them requires hand-
| written HTML/CSS. Trying to create a complex structure like a
| table is painful (if not unworkable) unless it's incredibly
| simplistic and small. It doesn't even natively support the most
| basic and universal feature of all documentation: a table of
| contents. If you want to document architecture, a DAG / flow
| chart, a comparison of tools, a series of products and what
| features they support, in-line snapshots of UX, etc, it's very
| painful (if not impossible) to compose such a document in
| plain-old Markdown.
|
| But I can throw such a document together in Confluence in 10
| minutes, and actually make it easy to both read and navigate.
| On top of that, anyone can find, access and edit it without
| special permissions or knowlege, and reverting changes is dead
| simple.
|
| Now, is it useful to generate documentation of code?
| _Absolutely!_ With Doxygen it 's been trivial for ages to have
| a rudimentary reference for all of your code. But this is not
| the same thing as the "Documentation" that most projects need,
| yet is always conspicuously lacking. Those docs are often more
| project-specific than code-specific and can't be generated
| automatically, because they are complex, subtle, and touch on
| many things at once.
| kaycebasques wrote:
| I think you're leaning too heavily on your own personal
| experience. You're stating things as absolutes that are very
| much relative depending on the context. The world of
| documentation is much broader than your definitions.
| sokoloff wrote:
| Twice in my career I've implemented a system to generate "good
| docs" from source. Twice I've failed. I've seen several other
| such initiatives which also failed. In every case, a more
| friendly editing experience won over the "check it in and type
| 'make doc'" experience. That could have been MediaWiki,
| Confluence, Box notes. People even preferred the abomination
| that is Sharepoint over a source-based system.
|
| If your docs are only written by developers, you might have a
| chance to make it work. If you need docs to be also
| written/edited by non-devs, I think you're looking at an uphill
| path to get everyone into source control-based docs.
| simonw wrote:
| That's absolutely true: the golden rule of keeping docs with
| code assumes that the documentation is /about/ the code -
| class and function descriptions or web API documentation for
| example.
|
| For product-level user-facing documentation written by non-
| engineers I think it's entirely appropriate to use a
| different tool.
| fragmede wrote:
| "product-level user-facing documentation written by non-
| engineers" is at one end of the spectrum, and clearly wants
| to use a different tool (eg Adobe InDesign) with code
| comments written by engineers at the other. Problem is, how
| do you navigate everything else that's in-between, while
| minimizing strife from one side making demands (some
| reasonable, others not) to the other.
|
| Where do your business critical spreadsheets go?
| karanssh wrote:
| I don't want to be "that" guy, but godoc in Go and how it works
| forces devs to write docs just beside code, which is one of my
| favourite things about the language
| blueyes wrote:
| Docs are like travel guides. When the underlying reality changes,
| they need to be rewritten. But most organizations barely make the
| effort for one good guide, let alone a guide that is rewritten as
| the code changes. So what happens is, they write a guide, go back
| to their business, and when a traveler says "hotel X doesn't
| exist anymore", they delete reference to hotel X. Not a great
| strategy! What's worse, it's a travel guide written by a real-
| estate developer. That is, the very people writing the guides are
| making their own guides outdated.
| z3t4 wrote:
| Documentation is underrated. If the documentation is bad I know
| it will cost 3x or more to implement. Most of the time I do look
| at the source code, aka "the source code is the documentation",
| but if the "source code" is 10000 modules with glue code, and
| there is no documentation - I will not even bother.
| mukundesh wrote:
| I hate viewing documentation in a browser, too many distractions.
| Everyone should distribute docs in a dockset format
| (https://kapeli.com/docsets).
| nzmsv wrote:
| Huh, looks like a modern-day WinHelp. That looks like it's
| moving in the wrong direction though. I doubt many people want
| a big completely offline doc blob in this day and age.
| mdaniel wrote:
| In my experience, local copies load appreciably faster and
| more consistently than CDN-ed, Google Analytics-ed hosted
| copies
|
| I'm beyond livid that Firefox Developer Edition stopped
| allowing me to paste "jar:" protocol URLs even though it
| still loads the existing ones I bookmarked just fine
| eddieh wrote:
| Actually, I wish more projects had installable documentation.
| Obviously, I don't want WinHelp, but man pages, HTML, and
| PDFs easily installed to a discoverable place, yes please.
| ofrzeta wrote:
| That's a good opportunity to mention Zeal, an open source Dash
| alternative: https://github.com/zealdocs/zeal
___________________________________________________________________
(page generated 2021-09-06 23:01 UTC)