It has happened to me multiple times that I’ve been writing the documentation for a system I’ve created, and found that it’s hard to even describe how to use the system, let alone to actually use it. I think “why can’t the system do all this automatically for me?”, and I fix the system to do exactly that, and then I’m relieved of the burden of having to write any documentation for how to do it manually. And as a result the system is better and easier to use for everyone.

Writing documentation is one of the best ways to realise that you never thought much about using it :). I do this all the time too.

This. Everybody should try call API / functions without actual implementation to see if it feels right.

Note: This is a noted positive side effect of doing TDD.

Documentation, too, needs debugging.

They can start by looking at the excellent documentation from FreeBSD, Gentoo, and others.

I think you forgot the best one: Arch.

BTW, I use Ubuntu. But for documentation I go to Arch.

I like Diataxis documentation framework. I wonder if there is an AI (or a systematic, automatable process) that could turn:

1. Actual executable programs into reference

2. References into how-tos (combine references into larger useful tasks)

3. References into explanations (extract common concepts and data structures)

4. How-tos and explanations into tutorials

I think an AI tool that could automatically provide documentation (higher-level conceptual description of how SW works or operates) it could be more useful than Github Copilot.

Part of the problem with documentation is is decoupling from code.

Therefore, when code changes, the documentation might tell a different story.

Documentation-as-code (i.e. doctests in Rust or Go) alleviates some of the shortcomings by showing how to use an API correctly.

The beauty of Docs-as-Code is that parts of it can even be generated. I'm thinking Diagrams-as-Code where the system under test can be i.e. queried for capabilities.

Since it's almost one year old? Has it paid off? Was there a noticeable betterment?

Hello, it's me, the author of the article. Thanks for asking.

I would ask not so much whether it has paid off or whether there was improvement, but whether it is paying off.

We're not done yet, we have really only just got started - it's a long-term project of transformation, that starts with practice and processes and people and will eventually show up in the documentation that's produced.

You can see evidence of it already in some of our documentation, it's the work of those engineering teams that have been spearheading the efforts, but it's all work in progress and we have a long way to go. (It's also all incremental work, so in general, there won't be dramatic big bangs to show.)

What you can't see from the outside are things like mindset, priorities and understanding of documentation - those are the things that will make for long-term success.

All the same, you remind me that it's probably a good idea to follow up that article with one pointing to some visible results.

I'm sure there's an official place I could ask this, but since you are here, maybe you could get some more detailed examples in place for the autoinstall [0] docs?

Specifically I'm about to try using the apt section, and I'm not exactly sure how to translate the curtin docs to the autoinstall format... Especially when it comes to adding keys. And a comment about needing to use exact bytes for normal partitions in the storage section would have saved me a few hours the other day... :)

Oh, and thanks for linking to that Diátaxis framework. I might have use for that at work.

[0] https://ubuntu.com/server/docs/install/autoinstall-reference

Is this why snaps don't include man pages? Because that's a damn shame.

I despise programs that do it. Especially if they went out of the way to make packages but manual is just "go to webpage, fuck you".

Also the dumb trend of doing

    command help subcommand

instead of

    command subcommand --help

it's annoying to have to back to the middle of the command just to add help there and get the manual

I agree but I think you misunderstood. Any program installed via Ubuntu Snap does not come with its man page, regardless of whether the authors wrote the best man page ever.

If you install via apt like normal, there's the man pages. Snap is canonical competitor with docker, ... Kinda

Yes. That is the problem. It should.

There should be a way to call snap in a way that gives you manual and it should be available via the usual cmdline tools

Oh thank god I thought I was the only one. This drives me up the wall - you get all the way through a command, go "oh wait, I don't actually remember what I need..." and the only thing `--help` does is print `For help please call command help the command you wanted`.

> it's annoying to have to back to the middle of the command just to add help there and get the manual

While I agree with the larger point of your comment, I work around this particular inconvenience of going back to the middle of the command by using the GNU Readline (or Zsh Line Editor in Zsh) key bindings. The key sequence to go back by one word and enter the new "help" argument is:

    command subcommand <Alt + b> help <Space>

In the Emacs/GNU Readline notation the additional key sequence can be expressed as:

    M-b help SPC

That's 7 extra key presses which is exactly the same number of key presses it would take to type and append " --help" at the end of an existing command.

Now time it, smartass

Now imagine you're 2 subcommands deep, smartass

Yes I know how readline works

Typing M-b to go back by one word to insert a new argument is of course going to be slower. It is going to be even slower when we are two sub-commands deep.

The M-b keybinding is merely a workaround, not a fix. I believe the snarky remark was unwarranted. I didn't mean to doubt your knowledge of readline. Like I said, I do agree with the larger point you made in your comment. I too find the non-standard help trends inconvenient. My comment was meant for sharing a workaround that helps me to alleviate some of the inconvenience caused by these problematic trends.

I like that git lets you get help either way, or via "man git-subcommand". Maybe it started the subcommand trend (it was the first big mainstream program I recall using it), but at least it keeps kind of faithful to the old skool way of doing things.

I remember when man couldn't handle

    man git command

and that was eventually added "a b" -> "a-b" translation.

Evil dark pattern on cookie settings - what a disrespect against your users.

Thin sans-serif body font means you hate your readers' eyes.

(I've mostly given up making this complaint, and things have gotten better, but I couldn't resist on an article on the importance of better documentation.)

> Documentation, when it exists, is usually a band-aid covering up bad design. Pretty documentation seems like lipstick on a pig.

The above two ideas are incongruent, but anyway, you do realize that system design can't be self-evident for complex systems? How for example would you have no documentation for the Linux kernel?

Either you're mis-communicating your point or not thinking of anything larger than tiny systems.

This is crazy. Documentation is indicative of bad design? Extensive docs, maybe. But simple docs and straightforward design go hand in hand.

Not quite; rather, much like comments, needing documentation is indicative of bad design. The general ordering (better to worse) for this phenomenon is:

don't need, don't have > need it, have it >> need it but don't have it

"don't need it, but have it anyway" can be better than don't-and-don't, but that varies depending on the quality of the documentation.

Makes me think of “Everything should be made as simple as possible, but not simpler” by Einstein. There’s a limit to how much complexity a good design can hide. Complex software that come to mine are package managers, disk partitioners, security software, container managers, and so on…they really need documentation.

This. Developers tend to assume that users are expert in the field domain, and that they'll know everything that happens to the application when they use its controls.

But not all users are well-versed on the purpose and possibilities of the tool, so documentation should at the very least give an overall view of those. And even experts need to read about the vocabulary, peculiarities and assumptions of how the tool works in that field domain.

Some of those explanation may be taught in-app through explanatory text and step-by-step guides (which are forms of documentation), but for tools more complex than a trivial phone app, documentation explaining the tool and detailing its primary workflows and use cases is a necessity.

Documentation is a hallmark of good design.