Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

The Grand Unified Theory of Documentation

diataxis.fr

Post reply on HN
Print view View original

21–30 of 58 posts

Re: The Grand Unified Theory of Documentation

#21

Post by eru »

hinkley wrote: post #11
rglover wrote: post #8

Some personal rules for docs: 1. Explain, in plain non-jargon words (nobody cares how smart you are) what problem is being solved, how, and why. 2. Provide contextualized examples (no foobar), not making assumptions about what the reader knows or doesn't know (and avoiding condescending language like "it's easy," "it's common sense" or anything that suggests the reader is "dumb" if they don't get it). 3. Think in ter…

I find that people tend to bristle at #1, in part because they tend to think about 'the document' instead of the giant pile of documents that will be produced over the next 3 years, and the fact that sooner or later you're going to be skimming multiple documents to figure out which one had the fix for that one problem or explained why on earth we made some dumb decision a year ago. This is most obvious with Wikis but…

Your point reminds me that you shouldn't think about documentation as a one-off thing you are doing for your project.

But in terms of a process. Eg how are you going to keep the docs up to date?

Re: The Grand Unified Theory of Documentation

#22

Post by neetrain »

eru wrote: post #19
npunt wrote: post #18

Earlier quoted context omitted.

Agree to all! When I was rewriting the OneSignal docs I followed the same rules you laid out as well as a few more: 5. Get every step right. Don't make assumptions that the reader knows how to configure something you mention in passing, spell it out. This is especially important if good engineers are writing docs since they leap over little things that less skilled users might not know. 6. Write for translators. Many…

About 8: this habit might make your docs sound a bit monotonous, but it also helps with 'grepping' through them.

I don't know whether it is only in my country, but teachers in school teach students otherwise. Not repeating the same word for the same things is alright for elegant literature, but problematic in the digital era.

Re: The Grand Unified Theory of Documentation

#23

Post by eru »

neetrain wrote: post #22
eru wrote: post #19

Earlier quoted context omitted.

About 8: this habit might make your docs sound a bit monotonous, but it also helps with 'grepping' through them.

I don't know whether it is only in my country, but teachers in school teach students otherwise. Not repeating the same word for the same things is alright for elegant literature, but problematic in the digital era.

Yes, literature and technical documents have different requirements.

Re: The Grand Unified Theory of Documentation

#24

Post by franciscop »

I find this troublesome because it attempts to categorize documentation in a synthetic way and then stops. While that's totally fine and a field on its own, this is not how people learn. It's akin as to saying that to learn French you need to categorize words as "substantives", "adjectives", "verbs", etc. Sure it's slightly useful, but it's just not how people approach learning.

Instead, and I mean to eventually write this long-form, I find it a lot more useful to think of documentation as a learning experience. You need several levels: for those who don't even know they want to learn it, for the beginners, for the seasoned that need a quick ref, for the ones who just lack practice, etc. In this way, tutorials will cater for a specific type of learners while the API docs will be a reference for those with already experience.

That is why I will also argue that library authors tend to go to the API docs. I read the docs of my own libraries, so while I have a feeling how it works I might want to quickly check the format of e.g. the second options argument. Since I wrote it, it's very useful for me to document the API since I already know how to get started or why to even use it. But that's not the same for others.

So I will argue that from the landing page (if any) to the API docs, there's no a strong divide and you should start teaching the user from the beginning. As an example, my projects tend to include a few-lines snippet as soon as possible.

PS, to do great documentation is a full-time job, and I still maintain that some ideal-ish ratio of lines of code vs testing vs documentation, given all the time in the world to work on it, is 1:5:10. as in, for each 1 line of code there should be 10 lines/paragraphs of documentation.

Re: The Grand Unified Theory of Documentation

#25

Post by BiteCode_dev »

smackay wrote: post #6

Doesn't the existence of blogs and Q&A sites like Stackoverflow indicate that current approaches to documentation are failing to deliver. I think there's more to the rise of cut & paste development than simply a lack of skill or a lack of time. The volume of state in some software systems is simply too great to put down in a linear document. Indeed the number of branches in state maybe too great to represent in any m…

Depends on the doc. If I have to do something with Django, VueJS or TailwindCSS, I always go to the doc first (mostly looking things up with "site:" in google though), because most of the time, it delivers.

If I have to create a db with one owner in postgres, I will not use the postgres docs.

Re: The Grand Unified Theory of Documentation

#26

Post by BiteCode_dev »

I love this doc because while it's not staying the whole story, it was basically my conclusion as well: you can't have one doc, you need several of them for different use cases.

I would had to the mix a page where jargon is defined, like a lexicon. You cannot, and should not always get away with jargon. Sometime you should (beginner tutorial), sometime you should define it inline (advanced tutorial), and sometime you should just use it (references), but with link it to the definition.

Re: The Grand Unified Theory of Documentation

#27

Post by Vinnl »

I've been trying to apply this approach, and it's generaly been a useful way of forming a holistic view of your docs.

The only quadrant that can be a bit challenging is the explanation: some projects are just relatively straightforward and don't require a lot of background knowledge about the whys. In that case, I've found it best to just stick to a couple of lines on the homepage explaining the project's background and the problems it's solving, rather than a separate, rather barren-looking section of your docs.

Re: The Grand Unified Theory of Documentation

#28

Post by Vinnl »

chillfox wrote: post #16
rglover wrote: post #8

Some personal rules for docs: 1. Explain, in plain non-jargon words (nobody cares how smart you are) what problem is being solved, how, and why. 2. Provide contextualized examples (no foobar), not making assumptions about what the reader knows or doesn't know (and avoiding condescending language like "it's easy," "it's common sense" or anything that suggests the reader is "dumb" if they don't get it). 3. Think in ter…

"(no foobar)" As someone with English as a second language seeing "foobar" all over the place in lot's of different contexts really confused me a lot early on. Especially when docs started talking about a "foo" and a "bar". I still don't understand why it is the generic go to word for examples, it makes little sense.

Likewise when learning OOP long ago, it seemed like every tutorial used a car with wheels and a steering wheel as examples. Took me a long time afterwards to understand how it could actually be used in practice.

Re: The Grand Unified Theory of Documentation

#29

Post by chillfox »

Vinnl wrote: post #28
chillfox wrote: post #16

Earlier quoted context omitted.

"(no foobar)" As someone with English as a second language seeing "foobar" all over the place in lot's of different contexts really confused me a lot early on. Especially when docs started talking about a "foo" and a "bar". I still don't understand why it is the generic go to word for examples, it makes little sense.

Likewise when learning OOP long ago, it seemed like every tutorial used a car with wheels and a steering wheel as examples. Took me a long time afterwards to understand how it could actually be used in practice.

Yeah, the entire car, engine and wheels thing really disconnected OOP from any practical use for me. It really took a long time before I understood how it applied to real code.

If real examples from a blog or accounting software had been used instead then I would likely have understood it a lot easier.

Re: The Grand Unified Theory of Documentation

#30

Post by ansible »

chillfox wrote: post #16
rglover wrote: post #8

Some personal rules for docs: 1. Explain, in plain non-jargon words (nobody cares how smart you are) what problem is being solved, how, and why. 2. Provide contextualized examples (no foobar), not making assumptions about what the reader knows or doesn't know (and avoiding condescending language like "it's easy," "it's common sense" or anything that suggests the reader is "dumb" if they don't get it). 3. Think in ter…

"(no foobar)" As someone with English as a second language seeing "foobar" all over the place in lot's of different contexts really confused me a lot early on. Especially when docs started talking about a "foo" and a "bar". I still don't understand why it is the generic go to word for examples, it makes little sense.

The word "foobar" has a long, long history in computers:

http://www.catb.org/~esr/jargon/html/F/foo.html

Post reply on HN