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

51–58 of 58 posts

Re: The Grand Unified Theory of Documentation

#51

Post by DanieleProcida »

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.

This is a good question.

Practical knowledge is knowing how to do something - tie your shoelaces, instantiate a model class, authenticate to an LDAP server.

Theoretical knowledge is knowing what is the case - that the cross-flow valves must be closed at take-off, that everything in Python is an object, what a Python property decorator does.

Technical reference is theoretical knowledge (that you apply in practice), as is explanation. Tutorials and how-to guide contain practical knowledge.

Re: The Grand Unified Theory of Documentation

#52

Post by remoquete »

kungito wrote: post #47
remoquete wrote: post #34

It's funny how little things have changed since software documentation started. Have a look at the Guideline for Software Documentation Management (1984 https://nvlpubs.nist.gov/nistpubs/Legacy/FIPS/fipspub105.pdf ) Documentation fulfills five important functions: - Communications to management about the progress of the project, providing intermediate product visibility - Task-to-task communication - Instruction and…

I'm very against this. You need resources allocated, that is developer time. I experienced having dedicated doc writers in FAANG and I wasn't happy with the experience. Our docs were mostly shit and for anything remotely specialized it was the developers who had to write the docs in the end. They were mostly proofreading or writing some non technical blog posts. It felt like they were an excuse for not forcing the de…

So your argument against technical writers is that you've had bad experiences with FAANG technical writers? And you think developers always have the time and skill for writing proper documentation? I wish that was true.

For certain types of documentation you need technical technical writers - for example, see http://hackwrite.com/posts/enough-to-be-dangerous/. And you need a proper content strategy / information architecture in place. Blame your recruiting managers and whoever wrote the job descriptions for not thinking about that.

Edit: And of course you need to allocate developer time. It's called knowledge transfer.

Re: The Grand Unified Theory of Documentation

#53

Post by samus »

johnchristopher wrote: post #33
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…

It may be due the language barrier or something but there are some phrasing that really throws me of: > You might send variables to this server function by calling this endpoint from your javascript code. You might but in fact you must (or you can) because it is the only way send variables to the server from Javascript. It's not like it's a personal preference or that there is another way. > You can choose to use `re…

The wording "might" really triggers me because it stands for something that /could/ happen. It is one of the ways to express the conjunctive mood (possibilities, wishes, ambiguity), which has absolutely no right to exist in a technical documentation.

~~There is only one place where this makes sense: in a best-practices section explaining consequences. But also there I want to see clear facts instead of unclear statements making me chase ghosts.~~

Edit: No, just plain facts please.

Re: The Grand Unified Theory of Documentation

#54

Post by remoquete »

franciscop wrote: post #24

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 wri…

I agree, and I encourage you to write all that down in a long form article. Technical writers and documentarians have kept silent for too long: It's time to change this.

Re: The Grand Unified Theory of Documentation

#55

Post by toomanybeersies »

johnchristopher wrote: post #33
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…

It may be due the language barrier or something but there are some phrasing that really throws me of: > You might send variables to this server function by calling this endpoint from your javascript code. You might but in fact you must (or you can) because it is the only way send variables to the server from Javascript. It's not like it's a personal preference or that there is another way. > You can choose to use `re…

This is where RFCs get it right (although technically they're standards, not documentation), with standardised language [1]

e.g.

> MUST: This word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification.

[1] https://tools.ietf.org/html/rfc2119

Re: The Grand Unified Theory of Documentation

#56

Post by swyx »

DanieleProcida wrote: post #43
swyx wrote: post #5

Earlier quoted context omitted.

wait so... this is a spinoff startup? i didnt even know what Divio sells..

Divio is a cloud management/application hosting platform. We use Docker for containerisation, and provide a unified integration layer to multiple different underlying vendors (AWS, Azure, etc). It means you can use the same tools (Control Panel, CLI, API) to create and manage cloud applications and their infrastructures on all those different vendors. The idea is that Divio takes care of infrastructure/DevOps concern…

thanks for the explanation!

i personally dont have this need at all (all in on AWS, and am ex Netlify and very friendly with Render) so havent really needed a unified integration for multiple vendors. good luck!

Re: The Grand Unified Theory of Documentation

#57

Post by bobthepanda »

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.

At least in the US my undergrad computer science degree had a course on specifically writing technical documentation

Re: The Grand Unified Theory of Documentation

#58

Post by MaxDPS »

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 like your point about condescending language. I’ve found myself using phrases like “It’s easy” in an attempt to not scare people away, but I see how that can backfire. I’m going to keep that in mind.
Post reply on HN