Wikimedia Release Engineering Team/Book club/What nobody tells you about documentation

EngProd Bookclub

Currently Reading: What nobody tells you about documentation

Random Notes

• thcipriani's random notes
• brennen's random notes

Attendees

• Z: Željko Filipin
• ET: Elena Tonkovidova
• B: Brennen Bearnes
• D: Dan Duvall
• T: Tyler Cipriani
• L: Lars Wirzenius
• J: Jeena Huneidi
• Mukunda Modell
• JR Branaa

Notes

• Z: needs to rewrite all documentation
• ET: made me think a lot about how to structure presentation/lessons
• B: Somewhat skeptical that there was a need for these specific divisions, but it made me reconsider
• LW: I thought it was a great framework, but it made me mad
• ET: I remember times when reference documentation was the only kind of documentation. Documentation used to equal references. To me "how to" is a subset of tutorials -- I don't see how they are distinct.
• Z: What I got from the article: A tutorial is the first step -- it gives you one or two examples of what you want to do with this thing. How to guides are for people who know what this software does -- i.e. when people already know your project and have questions. Article is the best thing I've read this year. I'm not sure that this is totally correct, but it's the best thing that I've read about it
• D: It's a model that imposes very clear constraints and have been applying it to the pipelinelib documentation. When I'm writing a tutorial, I really want to explain what's going on. It's an aggrivating process to follow, but I found it important to have those constraints. What it doesn't address is how to lead users from one modality to the other. In a way that gives them the opportunity to move from one type of doc to the other. Serving all the different types of readers is the challenge I think
• B: most places I've worked at with an emphasis on documentation have arrived at a similar scheme. Something like this tends to emerge for people working on these problems, but I don't know that it's always this explicit/cohesive. Digital ocean had distinctions between types of documents
• Z: Is anyone else aware of a similar framework -- this really resonated with me -- I'm sure there are other things that I'm not aware of...right?
• B: I think there's material out there. Write The Docs, etc
• Z: what I really liked is that different people learn different ways -- explanations are not good for me, but tutorials and how-to guides. You need a little of everything. Splitting into these groups is helpful for thinking about what documentation is missing
• ET: I strongly recommended it to everyone on my team. I always look from the practical point of view -- which of these would be *most* valuable?
• Z: I think I would disagree. Different people think differently. How much of each? It probably depends on the project.
• L: this article was too absolute as "THE WAY" to do it. One of the things I've learned is that audience is the first thing you think about. For example, this article says you have to have tutorials; you will still have to tailor this to your audience; i.e., the seasoned sysadmin vs absolute beginners. That's one aspect of the article that didn't make me happy. When I was learning how to write: who? what? where? when? why? how? This is not just for newspapers and fiction, but also for technical writing. If you want to write good documentation these are things you need to consider.
• Z: I think that lars is correct; however, I think you can do that within the framework: what's in scope and what's out-of-scope for a particular type of documentation. Now we have a shared-vocabulary!
• J: in the video he said not to put docs on a wiki -- he doesn't like wikis -- although he didn't elaborate
• B: The wiki example shows that there are lots of things not in this framework
• Z: framework is also useful for putting websites in a context: wikihow: how to; wikipedia: reference; blogs: explanation
• J: tutorial and how to and hard to distiguish
• ET: that was my first question as well

• T: terms were bad
• L: ontologies are always difficult and never correct. Author's background is Django (and related). Disucssion makes more sense in that context. Javadoc is useless
• D: javadoc is terrible
• Z: terms: "tutorials" == "getting started guide" -- tutorial is too generic. "How to guide" is an OK term. "reference" is a good name. "explanation" not sure about that.
• T: bad experience with auto-generated docs
• B: Perl is good at this -- dunno if this is cultural -- maybe this a question of how people are using the tools
• Z: Webdriver.io has a really useful reference/api usage. Javascript also has a good one that will complain if the docs/code disagree.

Open/new questions

• D: how to move users from one type of doc to the other?
• ET: which of these is most valuable?
• Z: How much of each type?