Making world-class docs takes effort | Hacker News Reader

Making world-class docs takes effort

daniel.haxx.se

97 pointstodsacerdoti22 comments

> 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.

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!

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.

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.

"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?

I think most documentation at a company can and should live outside of version control repositories - the key thing is to have editing tools that non-engineers can use and to ensure that the resulting material can be effectively published, searched and made visible to the people who need access to it.

The exception is engineering documentation: API docs should absolutely be version-controlled in the same place as the code they are describing.

I built an internal search engine for a past employer that covered 11 different sources of documentation - Confluence, Google Docs, GitHub Markdown, Salesforce Support and more - and it really helped solve some of the discoverability problems we were having.

> For product-level user-facing documentation written by non-engineers I think it's entirely appropriate to use a different tool.

I fantasize about an environment where a GUI's internals and interfaces are annotated sufficiently to discretely call from unit and integration tests, and version-controlled instances of those are linked to non-technical task management, user documentation, support tickets, support knowledge bases, patch configuration management, and so on. In this fantasy, if code changes a GUI element enough to alter its appearance or fail a unit test of the GUI, it automatically triggers a re-imaging of snapshots for it in all downstream linked documentation references and issues PR's for human intervention reviews of the new images (with adjustable cropping for finalized approvals).

That's my holy grail of single-source documentation.

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.

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.

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.

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...

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...

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.

> 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?

I hate viewing documentation in a browser, too many distractions. Everyone should distribute docs in a dockset format (https://kapeli.com/docsets).

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.

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

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.

That's a good opportunity to mention Zeal, an open source Dash alternative: https://github.com/zealdocs/zeal

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.

Making anything world class takes effort. /s

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

Reply on news.ycombinator.com