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

11–20 of 58 posts

Re: The Grand Unified Theory of Documentation

#11

Post by hinkley »

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 it applies to an extent to all documentation.

Remind me why I'm here in this document, because I might be in the wrong place.

Re: The Grand Unified Theory of Documentation

#12

Post by dnautics »

formerly_proven wrote: post #2

In case you went "hey, this looks like a blatant rip-off of Divio's pages, doesn't it?" -- yeah it is, because this is the spin-off of that particular aspect from Divio.

can you provide a reference link so that some of us can understand Divio? Thanks!

Re: The Grand Unified Theory of Documentation

#13

Post by benrbray »

1MoreThing wrote: post #7
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…

Why shouldn't the creation of knowledge and expertise come with a price tag? The question is "is it cheaper to create a system that creates new expertise than it is to hire someone with that expertise?" As long as the cost of the system is less than the cost of the generated expertise on the open market, it's a worthwhile investment.

Sure, we could assign price tags to every human interaction and never stop. But isn't it better for everyone to build a collective wiki of knowledge that we can all share and rely on? If I spend an entire day digging through the webpack documentation to perform a certain task, I'll gladly share that knowledge freely with anyone who asks, because I think it's a complete waste of human existence for each of us individually to learn how to wrangle webpack into submission.

The question becomes: If I've already put in the work, what cost is there to me to make my knowledge freely available in the form of a SO answer? Usually the answer is "not much".

(I'll be sending you an invoice for this comment)

Re: The Grand Unified Theory of Documentation

#14

Post by dnautics »

somethingAlex wrote: post #4

In regards to that four-quadrant infographic - how could Technical Reference fall into the category of "theoretical knowledge?" I'd think tutorials would fall under theoretical because if it gets too practical, are you not effectively writing a how to guide? I'm not really sure the four categories fit into that quadrant scheme as well as they'd like.

I'm not sure why this is being downvoted. I'll throw in my two cents (not the OP or anything):

It's not theoretical knowledge in the sense of "theoretical/applied physics", but rather theoretical knowledge because there is an extra step between it and application.

So if I give you a list of functions in a module/class and just tell you what they do, that is more theoretical than a code block that you can cut and paste as running code.

I'm not sure how else you would label this axis, theory/practical seems just fine.

Re: The Grand Unified Theory of Documentation

#16

Post by chillfox »

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.

Re: The Grand Unified Theory of Documentation

#18

Post by npunt »

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…

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 users don't speak English well and will be running docs through Google Translate. This is a variant of your #1.

7. Consider docs a seamless extension of the product. Use the exact wording and same visual language of the product and make sure docs pick up from where exactly the user was in the product. Evaluate these flows so wherever someone gets tripped up, the right doc is there waiting. Ideally do bidirectional linking so the product itself also links to these.

8. Super consistent language. Figure out your nouns and verbs: someone playing a game is always a 'player' (vs sometimes a 'user' or 'gamer'), someone sending a file is always 'transferring' (vs sometimes 'sending' or 'uploading'), etc. Unless you pay close attention ambiguity is going to creep into documentation.

Re: The Grand Unified Theory of Documentation

#19

Post by eru »

npunt wrote: post #18
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…

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.

Re: The Grand Unified Theory of Documentation

#20

Post by eru »

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.

I guess it's a combination of people following earlier example, and that it sounds funny.

In economics textbooks, companies always produce 'widgets'. https://en.wikipedia.org/wiki/Widget_(economics)

Post reply on HN