Four kinds of documentation • Hacker News Board

Re: Four kinds of documentation

#201

Post by kazinator » Mon, Oct 21, 2019, 8:02 PM UTC

otterley wrote: post #104

zomglings wrote: post #89

Earlier quoted context omitted.

I always found Kubernetes API reference very useful.

Yeah, that part was always fine, but they sorely lacked a theory of operations -- which is essential for any sort of state machine or orchestrator! -- and basic "man page"-type documentation around processes, config files, etc.

API's and programming languages are indeed very difficult to use effectively without documentation.

They are also not operating system user interfaces, productivity tools, games or web-browsers, and so not the topic of my little sub-thread here.

Re: Four kinds of documentation

#202

Post by gautamsomani » Fri, Oct 25, 2019, 11:15 AM UTC

franciscop wrote: post #125

kaycebasques wrote: post #64

As a practicing technical writer I can testify that these content types are a common way to organize your documentation collection and identify gaps. It’s a useful exercise to list each doc as a row in a spreadsheet, and then mark whether each doc is a tutorial, guide, conceptual overview, or reference, or a confused combination. Many times you’ll see that you have explained how feature A works but have no tutorial t…

As an OSS author this is very interesting, could you share more info or references about this please? Also I'm curious, how do you become a technical writter? Does it involve writing articles/blogposts/etc to promote the project?

https://www.linkedin.com/in/kaycebasques/

This should help you :)

Re: Four kinds of documentation

#203

Post by jest » Sun, Oct 27, 2019, 7:24 PM UTC

bbanyc wrote: post #185

Back in the early days, the printed manuals for Research Unix and BSD consisted of two volumes. Volume 1 was the reference and consisted of all the man pages for every command (section 1), system call (section 2), library function (section 3), etc. Volume 2 contained longer documents - what this article calls tutorials, how-tos, and explanations. The man command let you read all the pages in volume 1. Volume 2 only e…

> Volume 2 contained longer documents - what this article calls tutorials, how-tos, and explanations.

Looks like this one: https://wolfram.schneider.org/bsd/7thEdManVol2/