17 ms·

Four kinds of documentation

717 points by arnsholt 7y ago

itamarst 7y ago
If you want to watch a video version: https://pyvideo.org/pycon-au-2017/what-nobody-tells-you-about-documentation.html https://pyvideo.org/pycon-au-2017/what-nobody-tells-you-abou...
Numberwang 7y ago
This is brilliant. "Explanation - Topic" sounds a bit wonky as a section/title. Does anyone have a suggestion what to call those types of articles?
- Angostura 7y ago
  Backgrounder? White paper?
- jtogrul 7y ago
  How about Deep Dive?
- kaycebasques 7y ago
  Conceptual overviews
  - Numberwang 7y ago
    Just 'Overview' might be good. Or 'In Depth'
- DanieleProcida 7y ago
  I also use "background" or "discussion". Someone else here suggested "rationale".
rikroots 7y ago
I think this article offers some very good advice about the need for different types of documentation to support software. I am far more likely to try a new piece of software if it comes with clearly signposted online documentation covering how to install/use the 'ware, and why to use it, in addition to a well presented technical reference. In my view, getting the documentation balance right is critical - having too much documentation (I'm staring at Google and AWS here) can be almost as bad as having too little of it. Making the documentation easy to navigate is as important, for me, as making sure the information supplied is accurate and up to date. My personal experience - principally from attempting to document my Javascript library[1-6] - is that generating the documentation is just the start of the process. Keeping that documentation accurate and up-to-date as I developed the library across minor and major versions soon became a massive burden which eventually led me to put further development on hold; the latest work I have done on the library remains in a branch on GitHub while I think of better ways of developing and presenting the necessary documentation around it. [1-6] - My different attempts to document my Javascript library, as a demonstration of how messy the whole process can get: [1] - http://scrawl.rikweb.org.uk/ http://scrawl.rikweb.org.uk/ - the Tour page, with "marketing copy" which attempts to sell the library to potential users. [2] - http://scrawl.rikweb.org.uk/tutorial.html#HTML5_page http://scrawl.rikweb.org.uk/tutorial.html#HTML5_page - the "Simple Docs" page is an excellent example of confused documentation as it tries to combine tutorial, how-to and explanation in the same document. [3] - http://scrawl.rikweb.org.uk/demos.html http://scrawl.rikweb.org.uk/demos.html - I added the "Demos" page to support the "Simple Docs" page; in fact the demos were (are) the visual testing regime I developed for the code base. [4] - http://scrawl.rikweb.org.uk/docs/ http://scrawl.rikweb.org.uk/docs/ - the "Technical" documentation - generated from inline comments in the source code. I chose the wrong tool to do this, as it expects the code base to be object-oriented; the library's Javascript (v6) is procedural/prototypal, and decidedly not modular. [5] - http://rikweb.org.uk/wp/ http://rikweb.org.uk/wp/ - at one point I decided that a good way to supply "how-to" information was through blog posts. This was one of my less clever decisions and quickly abandoned. [6] - http://scrawl.rikweb.org.uk/learn.html#lesson001 http://scrawl.rikweb.org.uk/learn.html#lesson001 - my best attempt at supplying potential users with tutorial documentation. Embedded Codepens make the experience a bit more interactive, but the results are probably too primary school given that my target audience for the library was more experienced front-end developers.
protomikron 7y ago
My pet peeve is auto-generated documentation from configuration files or source code. It is absolutely useless and I would rather prefer no documentation than auto-generated. Some time ago Swagger (nowadays OpenAPI) got really popular and many projects "had an API" and pointed users to their green autogenerated API documentation clusterfuck. When time went on this green page would become an indicator for me, that the project does not work and I should be very sceptical - I am sure there are projects that do it better, but for me no-content auto-generated documentation is a real code smell.
- remotedeveloper 7y ago
  I work with a very large, complicated piece of software which has quite a comprehensive API but it's basically CRUD on top of a database. There is zero documentation about what happens when you update an object - only OpenAPI. To find that out, you would have to dig in to the database triggers. Half of working with it is trial-and-error and the other half is hope-and-pray.
  - JoeAltmaier 7y ago
    Same here. Why is documentation standard so low? Tell me how that buffer management works (do I provide it? delete it? when? how?); how threading is supported (reentrant? send/receive at the same time/different threads? interprocess?); dependencies (necessary initialization? teardown? states in between?); efficiency (can I hold a lock around the call? does it block?). Instead, we often get nothing but a method name and argument types. Ridiculous.
    - afarrell 7y ago
      > Why is documentation standard so low? Even in companies where good documentation would raise revenue in a way that the sales team notices[1], someone still needs to write it and someone still needs to make the business case for writing it. Engineers could, but many don't. If you're passionate about good documentation, but don't think you can deliver, it would be foolish to unless someone else is doing the writing. I'm a bit of an extreme case, but Many engineers feel so incredibly uncomfortable with writing prose that they avoid it. Why? The standard of writing education for STEM-minded people is low. Why? Writing education in high school is focused on literary analysis essays rather than on learning to describe facts and systems with vibrant clarity. [1] https://getputpost.co/overhauling-api-docs-with-gocardless-90cc2e656750 https://getputpost.co/overhauling-api-docs-with-gocardless-9... --- Anecdote: At age 14, my school had poster which listed the professions one could use mathematics in. Someone pitched us on how much need there was for people who could program. Shop classes and science classes had assignments which were miniature versions of problems we could see in the real world. Nobody did this for literary analysis. I didn't know how to ask "why are we doing this?" other than as a snotty teenager saying "Hey english teacher! Justify why your life's work has meaning." In reality, I wanted to say "I'm having trouble getting oriented around this subject. I'm having trouble understanding what it means to make progress or make something good. Can you help me?" I searched for writing advice devoured works like Politics and the English Language and Strunk and White. But they just helped me get better at editing, not at putting thoughts onto a blank page. Anecdote: At age 17, I told my English Literature teacher that I wanted to write really good physics tutorials. She looked confused at me and said "Why? Thats so boring." At age 17, I didn't have the self-confidence to persist to find a different teacher who would be interested in that. Anecdote: At age 20, in an engineering university, I knew that I struggled with getting the first draft of an essay done. I went to the writing center at my school. But I never built a good workflow with them for how to get the first-draft-writing process. I didn't know how to learn to write without an anxiety so strong that I felt compelled to dig my nails into my skin. I didn't know how to ask professors or TAs for help. I accepted that writing was just staring at the paper until my eyes bled. I wasn't going to learn to write. I endured my required writing classes. hoped that once I graduated, I might be able to work in a way to Anecdote: At age 29, I had to quit a visa-sponsoring software engineering job and very quickly find a new one, because of my failures with writing first drafts interacted with a business process for immigration-law compliance. --- I've now found two coaches and plan to spend this Saturday working on a first draft of a blog post and trying some of their strategies. Wish me luck.
blakesterz 7y ago
"Documentation needs to include and be structured around its four different functions: tutorials, how-to guides, explanation and technical reference." I'm a sysadmin and most of the documentation I write is... well it's for me! I do something once and I know I'll do it again, I copy and paste everything I did into our "docs" area so I can just copy and paste it again. I guess that falls under tech reference. My theory for these docs is if I'm not around, someone else should just be able to copy and paste things and not need to learn my job. Doesn't apply to EVERYTHING, but it helps for all the little things.
- Angostura 7y ago
  Presumably, someone else is writing the other 3 types of documentation for the actual users?
Crinus 7y ago
This is a nice article (though i think a bit too wordy). Note that what it calls "tutorial", "how-to guides" and "explanation" is sometimes called "guides", "howtos" and "rationale". As an application of this, I always thought that the Windows API help, especially those around Win3.1/95 had one of the better approaches for an API/library: the API is split in functional parts/groups (windows, fonts, messages, fonts, controls, etc) and for each group there is an "overview" section (e.g. Windows introduces the windows concept), then a reference (often split in several parts itself) and finally one or two examples (though that was optional). The help itself didn't have "howtos" or "rationales" but those were available through MSDN (later at least) as knowledge base articles. (modern winapi documentation is a mess on that regard, especially if you do not already have a vague knowledge of what you are looking for, because even though it is largely the same text, they have split and moved things around too much and put irrelevant distracting links everywhere) On the Unix world, the original X11 documentation follows a similar pattern, though for other more recent projects there is usually a very one-sided approach: as the article says, most projects only provide API references and perhaps a single (often unfinished) tutorial. GNU projects usually have documentation in texinfo which is laid out as a book and is often very good (most disagreements come from the default GNU info viewer, not the source documentation system that allows for HTML and PDF output nor really the info format itself that has more usable viewers like tkinfo). It also has a similar approach as the Win3.1/95 docs, though i think the lines between "guide" and "reference" are often blurred. This largely depends on the project though (e.g. the glibc manual has these better divided, whereas the bash manual tends to be more "blurry"). Also i'm not fan of GNU's style of function references - i prefer the more common/manpage-like style where for each function/macro/struct/etc you have an isolated page a very brief description about its purpose, its declaration, a list of what each parameter (for functions and macros) does, its return value (if any), a detailed description (if necessary), any requirements (e.g. headers, for APIs with multiple headers) and links to other relevant functions and guides. Also i find examples for each function to be nice though this is even more rare than guides. As a sidenote, i loathe autogenerated documentation and "docgen comments" in source code (and not only because they tend to enforce the "reference-only" approach). I think those should be totally separate and not pollute the code with documentation (especially headers as that makes it harder to read the headers that also act as a quick overview for an API). Though having a tool to automatically check docs and sources for mismatches (missing functions and/or functions with wrong declarations in the docs) is helpful. But i'm not aware of anything that does that.
lallysingh 7y ago
Yes, this is critical stuff!! I've seen a lot of effort put into unguided documentation efforts that put out huge, unapproachable times that helped nobody.
- arjenschat 7y ago
  Indeed. We have simple process to create maximum support impact with minimal effort in documentation. With every support request we ask ourselves: Why is this person contacting us? Is there a simple ui change or wording to prevent confusion. Basecamp coined the term "wordsmithing" for this endless process of fine tuning. [1] Only after we are happy with the amount of support request a feature generates, we document it. Doing it this way has a couple benefits. You kind of create a long term user test. You can't spoil the user with knowledge from documentation. There is no way you can give hits to the user to perform a the task. With every support request you can multi variant test your explanation. [1] https://signalvnoise.com/posts/3633-on-writing-interfaces-well https://signalvnoise.com/posts/3633-on-writing-interfaces-we... (2013)
austincheney 7y ago
What I have found helpful with documentation is when it is stored in a single location of the project and automatically formatted to various output formats: markdown, html, stdout, and possibly pdf.
arjenschat 7y ago
What we've learned is that you can roll the how-to guides and tutorials into one. Once a users has learned how to use a service, they only need some inspiration on how to use it in different scenario's Van der Meij, H Wrote a nice article [1] about minimalism in documentation referring to the first how-to guide (First_Minimal_Manual) [2] on how to use smalltalk for an IBM Displaywriter System (1980). This guide is all about just getting started, and if something goes totally wrong, you just reboot the machine. People learn by doing. For new user, unfamiliar with your service, you have to reassure them that they can undo everything. This allows them to explore the system freely without any anxiety of doing something permanently wrong. People prefer to be shown what todo instead of being told what to do. Ikea and Lego manuals for instance never tell you to put screw B1 into hole 7A in the right side of panel 14B Screenshots in your help center articles help a great deal with this. But these are hard to maintain, that is why we created Cliperado [3] [1] https://www.utwente.nl/en/bms/ist/minimalism/ https://www.utwente.nl/en/bms/ist/minimalism/ [2] https://www.utwente.nl/en/bms/ist/minimalism/displaywriter.pdf https://www.utwente.nl/en/bms/ist/minimalism/displaywriter.p... (PDF) [3] https://cliperado.com https://cliperado.com
- Already__Taken 7y ago
  As long as your tutorials aren't so basic as to be useless in practice you can roll them together sure.
- DanieleProcida 7y ago
  That is interesting - my experience is the opposite, that how-to guides and tutorials are the most-commonly confused types of documentation. My aim is to make the serve totally different needs: * tutorials: I'm in charge (the teacher) and I know what the new learner needs to grasp and become comfortable with so that they gain sufficient basic confidence and skills. In the tutorials, the beginner doesn't even know what questions to ask or what language to us when asking questions * how-to guides: the user is in charge; they are able to formulate the questions, and have the basic confidence and skills. What they need from me are the recipes. As described, it's the difference between teaching a child to cook, and a book of recipes for somebody who already knows the basics of cooking and the kitchen but wants to know how to cook a particular thing. If you get teaching a child to cook mixed up with a book of recipes everybody concerned will have a bad time. It matters most for the child, they will never want to learn how to cook with you again. The same go for tutorials in my experience.
Angostura 7y ago
Good article. The division between different types of documentation is something that I've understood intuitively, but never codified in this way.
smush 7y ago
These 4 split ideas are great. I've previously maintained a wiki for our department and the most viewed documents are always shifting from year to year. Until now, I've never been confident enough to act on the bits of information I've gotten from people who said they liked X article because Y, and now I can see that those articles are a mish-mash of the how-to and technical reference. Now I will be able to use this as a framework for my continuing revisions, and be able to ensure that for any subject I want to be able to expect others to teach themselves to understand, I need to have the 4 quadrants ready to go. Sidenote: I loath the excuses I hear so much these days about self-documenting code obviating the need for __any__ documentation or code comments at all. I'm always looked at like I'm a woozle for pushing back on that. I can't decide if that POV comes from laziness or a sense of denial (this is fine) but that's a rant for another submission.
acidburnNSA 7y ago
Python developers: you can now make teaching tutorials in Jupyter notebooks and have them get automatically executed during the documentation build process and converted into theme-matching HTML by Sphinx with an extension [1]. I fired it up the other day and it's really glorious for tutorials. They're guaranteed to be up to date when you build the docs. Before that, I had a unit test that ran the tutorial with comments all over both the doc and the test that said YOU HAVE TO UPDATE THE OTHER IN SYNC! [1] https://nbsphinx.readthedocs.io/ https://nbsphinx.readthedocs.io/
- AstralStorm 7y ago
  Not just Python, Jupyter has plenty of backends. Including C++. Word of warning though, you might be tempted to use the tutorial prototype style for an actual application. That doesn't work in general.
- closed 7y ago
  nbsphinx is super handy! A cool tool to combine with it is jupytext, so you can keep your notebooks as rmarkdown files, which is a bit more human readable / GitHub editable. I did this with a recent library, siuba, and have not regretted it! https://github.com/machow/siuba/tree/master/docs https://github.com/machow/siuba/tree/master/docs
harimau777 7y ago
My experience has been that having names for things makes it easier to think and communicate about them; including in documentation. For example, once I learned the term "tail" I no longer had to say "every element except for the first one". As another example, learning about "complete" versus "partial" functions gave me the vocabulary to better understand and communicate about certain types of errors. Does anyone know of any resources that describe different types of useful vocabulary such as this?
- andorov 7y ago
  I think it is also useful to be aware of the specific terms your team might need and introduce words to those more abstract concepts. This frequently happens with naming specific code patterns or important classes in the code, but can also be for how the team operates in general. A DSL for how your team operates.
  - LeonB 7y ago
    A glossary is a good thing to maintain. We keep one often updated in our wiki (at work)
- arjenschat 7y ago
  Being THE term is the holy grail for consumer brands. You can only get huge when your brand is the synonym for a whole concept or industry. Like ColaCola, Uber, Facebook, Tweet etc etc. For example Mark's explanation of Facebook [1] or the Photocopier sketch [2] Edit: fixed link order [1] https://youtu.be/cUNX3azkZyk?t=135 https://youtu.be/cUNX3azkZyk?t=135 (video) [2] https://www.youtube.com/watch?v=PZbqAMEwtOE https://www.youtube.com/watch?v=PZbqAMEwtOE (video)
  - c22 7y ago
    You've got your hyperlinks on backwards.
- agumonkey 7y ago
  It's a bit of a generic issue. Until tail becomes a norm, it's hard to understand. I found embedded test/examples pretty great to quickly get the meaning of an idiom. in python for instance: def tail(l): ''' >>> tail([1,2,3]) >>> [2,3] >>> tail([]) >>> ValueException("undefined on []") ''' # actual logic
bryanrasmussen 7y ago
Well I know they never tell you we don't have any. which would be the truth most of the time.
commandlinefan 7y ago
What I’m always looking for with technical documentation - which I rarely if ever am able to find - is, what problem is this thing is trying to solve? How is, say, Angular better than plain-old Javascript? How is Spark better than a shell script triggered by a cron job? How is Spring better than Java by itself? What sorts of problems are they most appropriate for? Sometimes I suspect that I can’t find this information because there are no problems that this thing actually solves…
- LeonB 7y ago
  Agree. Comparisons (head to head) are a different category again. And hard to find (apart from as partisan sales pitches). Particularly useful if you know X and wondering if/why to consider Y. I often look at “alternativeto.net” to find products/services because we often choose things based on similarity and points of difference with things we already know.
- uhoh-itsmaciek 7y ago
  And how it's worse! It's extremely rare, but some projects do tell you, "If you need X, consider Project Y instead."
- roelschroeven 7y ago
  Webpages of many many projects do this very badly. I mostly resort to reading the corresponding wikipedia articles, if any, which often are clearer about what the project does and how it relates/compares to other projects.
  - commandlinefan 7y ago
    > Webpages I've had hit or miss success even when I drop $50 on an O'Reilly book on the topic.
- Crinus 7y ago
  I'd generalize this with a "why". Why does this project exist? Why does that functionality exist? Why does it uses those types? etc (though you could say that this is part of the "Explanation" quadrant)
jrd259 7y ago
Two more categories of documentation: FAQ and trouble-shooting guide. Maybe you could call online chat-bots "documentation" (for trouble shooting or how-to?) but I've never seen one that actually did any good.
aasasd 7y ago
At last! I wanted to write something like this myself, only I identified two types so far: tutorials and reference. Lots of projects only have reference docs, some only have tutorials. Using one instead of the other is a pain. Having at least these two would be splendid for most projects. My ‘favorite’ example (in the bad sense of ‘favorite’) is Ansible, which had only tutorial docs for its YAML-based programming language―which they didn't want to recognize as a programming language. As a result, whenever I needed to look up some feature, I had to guess where in the tutorials it's likely to be introduced. Notably, plenty of important details are delivered as side notes sprinkled liberally all over the tutorial. (This was the situation with Ansible a couple years ago, something may have changed since.)
- bordercases 7y ago
  It would be cool to have a documentation style that embeds reference in the tutorial à la Tufte notes.
kaycebasques 7y ago
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 that shows how to use feature A, or vice versa.
- franciscop 7y ago
  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?
  - carapace 7y ago
    *writer ;-P
  - gautamsomani 7y ago
    https://www.linkedin.com/in/kaycebasques/ https://www.linkedin.com/in/kaycebasques/ This should help you :)
jpincheira 7y ago
Thanks for sharing this guide. It's fitting like a ring to finger as I am in the process of setting up documentation for the features of my app [1] because I realized that as an early-stage startup one of the best ways to teach your users how to use your product is by writing great documentation. I'm finishing the setup of this site within my landing now using Gatsby, on the main domain, so that it can also help to bring in more traffic from search engines. On the same topic, today I was listening to a podcast [2] titled "Getting traffic to a new website without blogging" which is excelent to match using Divio's guide. [1] https://standups.io https://standups.io [2] https://podcasts.apple.com/us/podcast/episode-344-getting-traffic-to-new-website-without/id656726654?i=1000451946117 https://podcasts.apple.com/us/podcast/episode-344-getting-tr...
- zomglings 7y ago
  Agreed. As someone making a very technical product, I can see how lack of documentation hinders my sales process -- potential customers want to try out my software, but the lack of documentation makes it difficult for them to overcome their inertia. As you did, I plan to spend the next couple of weeks just writing docs. Just want to lend weight to your comment. :) Thank you for posting the podcast.
  - jpincheira 7y ago
    Seems we're both in the same boat! Exactly. If on live demos, they go like "wow, didn't know this case". That's exactly what you should go write after. I have a huge list of things to write about. Hope you enjoy the podcast, there are some gems there about SEO. Ruben Gamez —the person in the podcast— was also technical and learned his way around SEO. Mind sharing what your product is?
    - zomglings 7y ago
      Very happy to share - my co-founder and I started a company called Simiotics, where we offer metadata stores for data, preprocessing functions/transforms, machine learning models, and statistics. We also have tools that integrate with these metadata stores to automate work that most data science teams perform manually today - running preprocessing jobs, updating models in production, monitoring the distribution of data and predictions in production models, things like that. Our pitch is that, instead of having to do complicated things like set up an Airflow cluster, spin up a Kubernetes cluster and build helm charts, manage Spark, etc., a data scientist can just call out to our APIs from their Python programs (which may be running in notebooks), and we take care of the stuff they need to do but don't want to do. This is our website: http://simiotics.com http://simiotics.com These are our docs: http://docs.simiotics.com http://docs.simiotics.com (They are in a very sorry state, and it embarrasses us to post them here, but we are going to use that embarrassment to push us to make them better!)
kazinator 7y ago
> if the documentation is not good enough, people will not use it. Counterexamples: people use operating systems, web browsers, various "productivity apps" and games without reading a shred of documentation.
- otterley 7y ago
  Kubernetes... (although the documentation has gotten better over the years, to the project’s credit) Ruby on Rails as well, for the first few years of its existence.
  - zomglings 7y ago
    I always found Kubernetes API reference very useful.
    - otterley 7y ago
      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.
      - kazinator 7y ago
        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.
- ipsi 7y ago
  Is that completely true, though? Almost all modern games include a (sometimes optional) tutorial, explaining the basics of how to play the game. Some number (a few? many? most?) of productivity apps will have in-app tutorials to get you up and running. Operating Systems... might have a tutorial? It's been a while sine I booted one up, and I'd likely skip it if present. On top of that, the GUI nature of these apps makes it easier to get started, I think, and even if there are _no_ tutorials, you can use your previous knowledge of similar apps and play around to understand it - click buttons, tap menus, etc, and learn by doing. I'm not sure where this fits into the documentation quadrant, but it's important, and is _why_ users can get away without reading documentation.
kissgyorgy 7y ago
Yes, there is a place where you can hear about those things: The Write The Docs community: https://www.writethedocs.org/ https://www.writethedocs.org/ (They also organize conferences every year.) It was really eye-opening when I visited a conference and heard those things the first time, it is highly recommended for everyone! https://www.writethedocs.org/conf/ https://www.writethedocs.org/conf/
- zomglings 7y ago
  Thanks. Did not know about writethedocs - that looks like a great community.
kozak 7y ago
Bad documentation covers obvious things very well, and doesn't cover tricky parts at all. This is especially what you get if the writer of the documentation is paid by the amount of written text: there is no incentive to spend time investigating the hard parts, but a lot of incentive to explain the easy parts in too much detail.
LeonB 7y ago
With reference docs, I really value the examples. Describing the syntax, in a formal way is necessary sure. But I often skip down to the examples and that way I get a feel for it quickly. Bonus points if the examples are thoughtful in the way they start with simple cases and move up to more complex ones while remaining practical and thus easy to imagine their usefulness.
ryanmccullagh 7y ago
Throughout my career as a software engineer, I've found myself reading source code to figure out how a piece of code works when there isn't sufficient documentation. As an example, writing a plugin for collectd is not very well documented IMO. So what does one do? Well, I know C, so I dove into the source code of collectd and was able to figure out how the API works.
sebastianconcpt 7y ago
The secret Documentation needs to include and be structured around its four different functions: tutorials, how-to guides, explanation and technical reference. Each of them requires a distinct mode of writing. People working with software need these four different kinds of documentation at different times, in different circumstances - so software usually needs them all. And documentation needs to be explicitly structured around them, and they all must be kept separate and distinct from each other.
luord 7y ago
As someone who might be adherent to "good code explains itself", this is a really great explanation of what documentation should actually be and how it should be organized. It's interesting how one of the projects that I for a long time have believed to have great docs is VueJS, and that documentation more or less adheres to these principles.
kerkeslager 7y ago
Some examples of what I consider to be good documentation: * RethinkDB * Stripe * Python
franciscop 7y ago
I am not sure if it's missing or it's part of one of these four, but another very important part for me is the introduction/README. Probably the most important one. Introductions include: - Project health indicators, all green. [tests | passing] and such. - Quick general description of the problem the project solves. - A simple code snippet showing how easy it is to use it. Not the most complex way of using it as many do, please. - Screenshots and gifs if it's UI-related. Very important if it's UI-related. - Quick installation guide if using a common way, or a link to an in-depth guide if it's not easy to install. - Links to other parts, in-depth articles, etc. Some examples where I think I got it right (feedback welcome!): https://github.com/franciscop/server https://github.com/franciscop/server https://github.com/franciscop/ola https://github.com/franciscop/ola That said, good documentation takes a lot of effort and time.
- anaphor 7y ago
  A great example of the simple code snippet is Flask https://palletsprojects.com/p/flask/ https://palletsprojects.com/p/flask/
- pstuart 7y ago
  > A simple code snippet showing... And the variable naming to make clear what is user vs. system defined.
- qplex 7y ago
  - One sentence describing what a project does (preferably the first sentence of a README)
- swinglock 7y ago
  franciscop/server > Powerful server for Node.js that just works so you can focus on your awesome project This is not a "quick general description of the problem the project solves" and I don't even know what the code does after reading this. You can do better than this.
  - franciscop 7y ago
    Agreed, I haven't liked that line for a while. What about something like this? > A server for Node.js that works out of the box with modern Javascript It is a Node.js server with a bunch of middleware so that you don't need to do common things like body-parser, cookies, etc. It's also based around async/await instead of callback-based, which makes it easier to work with more modern JS and that prevents me from calling something like "express wrapper" or similar.
franciscop 7y ago
Good documentation IMO strongly depends on the project scope. There are many small projects that benefit from having a single, well structured long readme because it's easier to read+use. But there are some other projects that really need the longer format and everything described in this article.
slx26 7y ago
this is a great summary. I also like to add proper information about the context, the required knowledge to tackle each part, and the goal of that part of the documentation itself. in most cases, you can write a couple lines at the start of a document saying: "this document explains A. you will be interested on it if B. you should already know about C and D before proceeding. otherwise, you might be interested on E or F instead." I also noticed an interesting situation when trying to write good documentation: if you start too early, you will have to update it and change it a billion times (both writing the docs and testing the systems will reveal a lot of parts that can be improved). but if you start too late, everything will seem to be ok until you try to write it down. when you have done a few high-level overviews and detailed technical references, that always reveals how the are a number of important parts that could be simpler and/or more harmonic. we always try to make code simpler, but sometimes we only discover simpler ways to express things when we are thinking about them in natural language. or the other way around. perspective++
nlawalker 7y ago
docs.microsoft.com has a taxonomy that's a superset of this: overview, quickstart, tutorial, sample, concept, how-to, reference, resources. Most of the tables-of-contents are organized around this. Example: https://docs.microsoft.com/en-us/azure/app-service/ https://docs.microsoft.com/en-us/azure/app-service/
- mark-r 7y ago
  The only problem with Microsoft is that they delight in rearranging their web site. I'll bet that link is dead within a year.
peterwwillis 7y ago
There's more than four kinds; the main point should be that they need to be written with their particular purpose in mind. Here's some categories that apply just to system operations: - Reference - Discussion - Planning - Tutorial/Educational - How-To - Process Template (many, many kinds) - Process Implementation - Q&A There are also attributes: Local/Global, Draft, Approved, Certified, Published, Restricted, Versioned, etc. There's the venue: Internal, Customer-facing, Regulatory, Quality Assurance, Development, Managerial, Executive, etc. Then there's the scope of the document: high-level, deep dive, navigation, etc. When you write documentation, you must know your audience, what they need your document for, whether your document gives them everything they need, whether it's clear & concise, and whether anyone can find it when they need to. They should know when it was written & by whom, what it was written for, who it applies to. It should provide references to everything someone needs to know to make use of the doc. And not only should the document be clear, it has to stylistically express detail and make the document easier to process.
zackmorris 7y ago
I use lack of ambiguity as a measure of documentation quality. The best (honestly the only good) documentation that I've ever found is at: https://www.php.net/<keyword> https://www.php.net/<keyword> For example: https://www.php.net/echo https://www.php.net/echo Note how even this simple arbitrary example tells us "No additional newline is appended." It's shocking to me how many other guides would leave something that critical out of the manual. Then there are even helpful examples beneath that showcase users' experiences and any errata that they've discovered. Contrast this with Ruby's manual: https://docs.ruby-lang.org/en/master/ARGF.html#method-i-print https://docs.ruby-lang.org/en/master/ARGF.html#method-i-prin... I can infer that to_s is probably to_string. But I'm already hit with several new concepts like $, $_ and $\ which aren't clickable, so now it requires work to track down what they mean. The related methods beneath (like puts) are similarly cryptic. A good percentage of the time in search engine results, I click both the Ruby documentation and Stack Overflow links. I don't remember ever really learning PHP, because I realized quickly into it that it was a thin wrapper fixing any operating system shortfalls, generally leveraging concepts and contextual cues from C, C++ and the shell. Meanwhile Ruby had one of the steepest learning curves I've ever encountered outside of functional programming, even though it's similarly based on Perl and the shell. So where Ruby is a "convention over configuration" language, PHP is more of an "existing context over surprises" language. Writing the documentation for a language or framework can reveal these surprises, and over time, improve the tech itself and lead to a better experience.
- alistproducer2 7y ago
  I have to agree. Php is probably the easiest and moat productive languages I ever learned. The docs were great and the error messages always pointed me im the right direction very quickly. It's no surprise that the language caught on as it did. Ruby, by contrast seemed so hard to learn and I could never see what the advantage was over php so I never had the motivation to push past the difficulties of learning it.
- degenerate 7y ago
  Also a major overlooked factor in PHP's documentation success is having a specific URL for each function. Some documentation sites use #anchors to jump to spots in a document (ex: boostrap), but it's not good enough. What ends up happening is people search Google for something granular like "mysql concat" and end up on tutorial sites like w3schools. Why? Because the MySQL documentation throws CONCAT() into a giant messy page called "String Functions and Operators": https://dev.mysql.com/doc/refman/8.0/en/string-functions.html https://dev.mysql.com/doc/refman/8.0/en/string-functions.htm... Google "mysql concat" and see for yourself. Giant one-page docs are terrible. PHP got it right from the beginning.
mitchtbaum 7y ago
(great article, docs broke somewhere along the way) so do it while making the stuff especially once you reach the end, have it working, and are talking about it as if it's right in front of you do. it. then!.. don't wait till people are asking about it like it's recently forgotten.. even then, you're talking about it like it's in front of you; good docs time (point: repair broken links before breaking & appreciate and accept broken-ness as default, afair) (inside: i have a dream of a well-documented world) (point2: remember)
RcouF1uZ4gsC 7y ago
I think the zenith of reference documentation was the Windows API documentation on the MSDN CD's of the late 90's.
- mark-r 7y ago
  Absolutely agree, those were incredible. Looking things up on the web is a pale substitute.
devy 7y ago
I like the way the author use Quadrant Analysis (derived from Gartner's Magic Quadrants research methodology[1], well not exactly the same quardrants but similar way of thinking.) to explain the "right" way to do documentation. [1]: https://www.gartner.com/en/research/methodologies/magic-quadrants-research https://www.gartner.com/en/research/methodologies/magic-quad...
HugoDaniel 7y ago
I love the SQLite source code, it has a good ratio of comments per line of code
arminiusreturns 7y ago
I like this article, and if I may I'd like to add a more meta comment. In my experience, the biggest issue is getting people to use documentation systems in the first place. For example I have absolutely grown to hate confluence. Without plugins, and even with, it's a mess that becomes a barrier instead of a conductor. Therefor, for technical people, I think the best documentation tends to be easily accessible raw text. I personally use a combination of emacs org mode and asciidoc/asciidoctor. If I'm already always in emacs, why not use something already right there, and is quick and easy? The structure is important, but people just need to actually write the documentation in the first place. So, just write, and you will build the skills to differentiate types as the article refers to.
dredmorbius 7y ago
In my experience, it's explanations and how-to guides which are the most essential, with a comprehensive reference filling in the gaps. I've virtually always found tutorials almost completely useless. I also have a major gripe with the guidelines for how-to guides: these should explain things, most especially where: 1. Not following the process precisely, or appropriately to circumstances will lead to major issues. 2. Where the function, significance, or mechanism of a given step is critical to understanding and correctly applying the tool. 3. Where the reason(s) for choosing amongst a set of options is helpful in making that decision. One of the best concise distinctions between science and technology I've found is from John Stuart Mill: technology is the study of means, science is the study of causes or mechanisms. Technology tells you how and science explains why. Both are crucial to advanced understanding and use. This doesn't mean that a cookbook approach needs to have detailed "why" explanations, but it should at least touch on these. The other hugely useful aspect of a good cookbook is that it shows you the range of performance, capabilities, or applications of a tool. Readers can either hunt through for their specific problem (or something close enough to it to be adapted), or look through the range of applications to get new ideas for projects or products. One of the best cookbook texts I've ever encountered is O'Reilly's Unix Power Tools, first published in the early 1990s and still relevant. Kernighan & Pike's The UNIX Programming Environment is strongly similar, and despite dating from the 1980s, and being substantially obsolete in part, remains a valuable reference. Straight syntax guides, say, the Bash manpage, are useful, but are complex and difficult to navigate especially for a novice, and even a user with decades of experience. Tools such as vim and emacs share this problem, and whilst references can be useful for specific command or feature syntax and behaviour, do little to expose the power and capabilities of such tools. Cookbook approaches are far more useful.
bbanyc 7y ago
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 existed in print, with the troff source in /usr/doc but no obvious way to find it if you didn't know where to look. So naturally volume 2 fell by the wayside. When I was learning Unix in the late '90s and early '00s I had no idea there was supposed to be "official" documentation besides man pages, and filled in the gaps with random web tutorials and borrowed O'Reilly books and other "unofficial" sources. Nowadays some "Unix purists" are insisting that man pages are all the documentation you could ever possibly need, and if the man page is too long that means the software is too bloated. I find that attitude to be ahistorical. Like anyone's going to learn to effectively use troff and eqn from a cut-and-dried syntax description. (I could ramble a bit about the other documentation formats that have sprung up to replace troff and how, nice as they can be, they don't replace the convenience of manpages, but this comment is long enough.)
- lliamander 7y ago
  > The man command let you read all the pages in volume 1. Volume 2 only existed in print, with the troff source in /usr/doc but no obvious way to find it if you didn't know where to look. So naturally volume 2 fell by the wayside. I guess my feeling that man pages were insufficient is not without basis.
- aasasd 7y ago
  Notably, Linux had a whole lot of howtos and faqs—not sure about authoritative sources but I guess The Linux Documentation Project is/was the largest. That was how people learned to do stuff without tearing their hair out, in the early–mid-2000s. I probably still have some of them lying around thanks to stockpiling like the apocalypse is nigh. Of course, sparse or arcane documentation also leads to proliferation of educating books, by people ready to help for a reasonable sum. The existence of which market should say something about the truthfulness of ‘manpages are enough.’
adamcharnock 7y ago
I saw Daniele Procida talk at Commit Porto on this subject and it was very compelling to me. I’ve often lacked for a way to structure my documentation and this really resonated with me. I’ve since refactored and expanded documentation for one of my projects [1] to be in this format and I think it has resulted in something more more coherent. [1]: https://lightbus.org https://lightbus.org
quipquopro 7y ago
A

717 points by arnsholt 7y ago

If you want to watch a video version: https://pyvideo.org/pycon-au-2017/what-nobody-tells-you-about-documentation.html https://pyvideo.org/pycon-au-2017/what-nobody-tells-you-abou...

Numberwang 7y ago

This is brilliant. "Explanation - Topic" sounds a bit wonky as a section/title. Does anyone have a suggestion what to call those types of articles?

Angostura 7y ago
Backgrounder? White paper?
jtogrul 7y ago
How about Deep Dive?
kaycebasques 7y ago
Conceptual overviews
- Numberwang 7y ago
  Just 'Overview' might be good. Or 'In Depth'
DanieleProcida 7y ago
I also use "background" or "discussion". Someone else here suggested "rationale".

rikroots 7y ago

I think this article offers some very good advice about the need for different types of documentation to support software. I am far more likely to try a new piece of software if it comes with clearly signposted online documentation covering how to install/use the 'ware, and why to use it, in addition to a well presented technical reference. In my view, getting the documentation balance right is critical - having too much documentation (I'm staring at Google and AWS here) can be almost as bad as having too little of it. Making the documentation easy to navigate is as important, for me, as making sure the information supplied is accurate and up to date. My personal experience - principally from attempting to document my Javascript library[1-6] - is that generating the documentation is just the start of the process. Keeping that documentation accurate and up-to-date as I developed the library across minor and major versions soon became a massive burden which eventually led me to put further development on hold; the latest work I have done on the library remains in a branch on GitHub while I think of better ways of developing and presenting the necessary documentation around it. [1-6] - My different attempts to document my Javascript library, as a demonstration of how messy the whole process can get: [1] - http://scrawl.rikweb.org.uk/ http://scrawl.rikweb.org.uk/ - the Tour page, with "marketing copy" which attempts to sell the library to potential users. [2] - http://scrawl.rikweb.org.uk/tutorial.html#HTML5_page http://scrawl.rikweb.org.uk/tutorial.html#HTML5_page - the "Simple Docs" page is an excellent example of confused documentation as it tries to combine tutorial, how-to and explanation in the same document. [3] - http://scrawl.rikweb.org.uk/demos.html http://scrawl.rikweb.org.uk/demos.html - I added the "Demos" page to support the "Simple Docs" page; in fact the demos were (are) the visual testing regime I developed for the code base. [4] - http://scrawl.rikweb.org.uk/docs/ http://scrawl.rikweb.org.uk/docs/ - the "Technical" documentation - generated from inline comments in the source code. I chose the wrong tool to do this, as it expects the code base to be object-oriented; the library's Javascript (v6) is procedural/prototypal, and decidedly not modular. [5] - http://rikweb.org.uk/wp/ http://rikweb.org.uk/wp/ - at one point I decided that a good way to supply "how-to" information was through blog posts. This was one of my less clever decisions and quickly abandoned. [6] - http://scrawl.rikweb.org.uk/learn.html#lesson001 http://scrawl.rikweb.org.uk/learn.html#lesson001 - my best attempt at supplying potential users with tutorial documentation. Embedded Codepens make the experience a bit more interactive, but the results are probably too primary school given that my target audience for the library was more experienced front-end developers.

protomikron 7y ago

My pet peeve is auto-generated documentation from configuration files or source code. It is absolutely useless and I would rather prefer no documentation than auto-generated. Some time ago Swagger (nowadays OpenAPI) got really popular and many projects "had an API" and pointed users to their green autogenerated API documentation clusterfuck. When time went on this green page would become an indicator for me, that the project does not work and I should be very sceptical - I am sure there are projects that do it better, but for me no-content auto-generated documentation is a real code smell.

remotedeveloper 7y ago
I work with a very large, complicated piece of software which has quite a comprehensive API but it's basically CRUD on top of a database. There is zero documentation about what happens when you update an object - only OpenAPI. To find that out, you would have to dig in to the database triggers. Half of working with it is trial-and-error and the other half is hope-and-pray.
- JoeAltmaier 7y ago
  Same here. Why is documentation standard so low? Tell me how that buffer management works (do I provide it? delete it? when? how?); how threading is supported (reentrant? send/receive at the same time/different threads? interprocess?); dependencies (necessary initialization? teardown? states in between?); efficiency (can I hold a lock around the call? does it block?). Instead, we often get nothing but a method name and argument types. Ridiculous.
  - afarrell 7y ago
    > Why is documentation standard so low? Even in companies where good documentation would raise revenue in a way that the sales team notices[1], someone still needs to write it and someone still needs to make the business case for writing it. Engineers could, but many don't. If you're passionate about good documentation, but don't think you can deliver, it would be foolish to unless someone else is doing the writing. I'm a bit of an extreme case, but Many engineers feel so incredibly uncomfortable with writing prose that they avoid it. Why? The standard of writing education for STEM-minded people is low. Why? Writing education in high school is focused on literary analysis essays rather than on learning to describe facts and systems with vibrant clarity. [1] https://getputpost.co/overhauling-api-docs-with-gocardless-90cc2e656750 https://getputpost.co/overhauling-api-docs-with-gocardless-9... --- Anecdote: At age 14, my school had poster which listed the professions one could use mathematics in. Someone pitched us on how much need there was for people who could program. Shop classes and science classes had assignments which were miniature versions of problems we could see in the real world. Nobody did this for literary analysis. I didn't know how to ask "why are we doing this?" other than as a snotty teenager saying "Hey english teacher! Justify why your life's work has meaning." In reality, I wanted to say "I'm having trouble getting oriented around this subject. I'm having trouble understanding what it means to make progress or make something good. Can you help me?" I searched for writing advice devoured works like Politics and the English Language and Strunk and White. But they just helped me get better at editing, not at putting thoughts onto a blank page. Anecdote: At age 17, I told my English Literature teacher that I wanted to write really good physics tutorials. She looked confused at me and said "Why? Thats so boring." At age 17, I didn't have the self-confidence to persist to find a different teacher who would be interested in that. Anecdote: At age 20, in an engineering university, I knew that I struggled with getting the first draft of an essay done. I went to the writing center at my school. But I never built a good workflow with them for how to get the first-draft-writing process. I didn't know how to learn to write without an anxiety so strong that I felt compelled to dig my nails into my skin. I didn't know how to ask professors or TAs for help. I accepted that writing was just staring at the paper until my eyes bled. I wasn't going to learn to write. I endured my required writing classes. hoped that once I graduated, I might be able to work in a way to Anecdote: At age 29, I had to quit a visa-sponsoring software engineering job and very quickly find a new one, because of my failures with writing first drafts interacted with a business process for immigration-law compliance. --- I've now found two coaches and plan to spend this Saturday working on a first draft of a blog post and trying some of their strategies. Wish me luck.

blakesterz 7y ago

"Documentation needs to include and be structured around its four different functions: tutorials, how-to guides, explanation and technical reference." I'm a sysadmin and most of the documentation I write is... well it's for me! I do something once and I know I'll do it again, I copy and paste everything I did into our "docs" area so I can just copy and paste it again. I guess that falls under tech reference. My theory for these docs is if I'm not around, someone else should just be able to copy and paste things and not need to learn my job. Doesn't apply to EVERYTHING, but it helps for all the little things.

Angostura 7y ago
Presumably, someone else is writing the other 3 types of documentation for the actual users?

Crinus 7y ago

This is a nice article (though i think a bit too wordy). Note that what it calls "tutorial", "how-to guides" and "explanation" is sometimes called "guides", "howtos" and "rationale". As an application of this, I always thought that the Windows API help, especially those around Win3.1/95 had one of the better approaches for an API/library: the API is split in functional parts/groups (windows, fonts, messages, fonts, controls, etc) and for each group there is an "overview" section (e.g. Windows introduces the windows concept), then a reference (often split in several parts itself) and finally one or two examples (though that was optional). The help itself didn't have "howtos" or "rationales" but those were available through MSDN (later at least) as knowledge base articles. (modern winapi documentation is a mess on that regard, especially if you do not already have a vague knowledge of what you are looking for, because even though it is largely the same text, they have split and moved things around too much and put irrelevant distracting links everywhere) On the Unix world, the original X11 documentation follows a similar pattern, though for other more recent projects there is usually a very one-sided approach: as the article says, most projects only provide API references and perhaps a single (often unfinished) tutorial. GNU projects usually have documentation in texinfo which is laid out as a book and is often very good (most disagreements come from the default GNU info viewer, not the source documentation system that allows for HTML and PDF output nor really the info format itself that has more usable viewers like tkinfo). It also has a similar approach as the Win3.1/95 docs, though i think the lines between "guide" and "reference" are often blurred. This largely depends on the project though (e.g. the glibc manual has these better divided, whereas the bash manual tends to be more "blurry"). Also i'm not fan of GNU's style of function references - i prefer the more common/manpage-like style where for each function/macro/struct/etc you have an isolated page a very brief description about its purpose, its declaration, a list of what each parameter (for functions and macros) does, its return value (if any), a detailed description (if necessary), any requirements (e.g. headers, for APIs with multiple headers) and links to other relevant functions and guides. Also i find examples for each function to be nice though this is even more rare than guides. As a sidenote, i loathe autogenerated documentation and "docgen comments" in source code (and not only because they tend to enforce the "reference-only" approach). I think those should be totally separate and not pollute the code with documentation (especially headers as that makes it harder to read the headers that also act as a quick overview for an API). Though having a tool to automatically check docs and sources for mismatches (missing functions and/or functions with wrong declarations in the docs) is helpful. But i'm not aware of anything that does that.

lallysingh 7y ago

Yes, this is critical stuff!! I've seen a lot of effort put into unguided documentation efforts that put out huge, unapproachable times that helped nobody.

arjenschat 7y ago
Indeed. We have simple process to create maximum support impact with minimal effort in documentation. With every support request we ask ourselves: Why is this person contacting us? Is there a simple ui change or wording to prevent confusion. Basecamp coined the term "wordsmithing" for this endless process of fine tuning. [1] Only after we are happy with the amount of support request a feature generates, we document it. Doing it this way has a couple benefits. You kind of create a long term user test. You can't spoil the user with knowledge from documentation. There is no way you can give hits to the user to perform a the task. With every support request you can multi variant test your explanation. [1] https://signalvnoise.com/posts/3633-on-writing-interfaces-well https://signalvnoise.com/posts/3633-on-writing-interfaces-we... (2013)

austincheney 7y ago

What I have found helpful with documentation is when it is stored in a single location of the project and automatically formatted to various output formats: markdown, html, stdout, and possibly pdf.

arjenschat 7y ago

What we've learned is that you can roll the how-to guides and tutorials into one. Once a users has learned how to use a service, they only need some inspiration on how to use it in different scenario's Van der Meij, H Wrote a nice article [1] about minimalism in documentation referring to the first how-to guide (First_Minimal_Manual) [2] on how to use smalltalk for an IBM Displaywriter System (1980). This guide is all about just getting started, and if something goes totally wrong, you just reboot the machine. People learn by doing. For new user, unfamiliar with your service, you have to reassure them that they can undo everything. This allows them to explore the system freely without any anxiety of doing something permanently wrong. People prefer to be shown what todo instead of being told what to do. Ikea and Lego manuals for instance never tell you to put screw B1 into hole 7A in the right side of panel 14B Screenshots in your help center articles help a great deal with this. But these are hard to maintain, that is why we created Cliperado [3] [1] https://www.utwente.nl/en/bms/ist/minimalism/ https://www.utwente.nl/en/bms/ist/minimalism/ [2] https://www.utwente.nl/en/bms/ist/minimalism/displaywriter.pdf https://www.utwente.nl/en/bms/ist/minimalism/displaywriter.p... (PDF) [3] https://cliperado.com https://cliperado.com

Already__Taken 7y ago
As long as your tutorials aren't so basic as to be useless in practice you can roll them together sure.
DanieleProcida 7y ago
That is interesting - my experience is the opposite, that how-to guides and tutorials are the most-commonly confused types of documentation. My aim is to make the serve totally different needs: * tutorials: I'm in charge (the teacher) and I know what the new learner needs to grasp and become comfortable with so that they gain sufficient basic confidence and skills. In the tutorials, the beginner doesn't even know what questions to ask or what language to us when asking questions * how-to guides: the user is in charge; they are able to formulate the questions, and have the basic confidence and skills. What they need from me are the recipes. As described, it's the difference between teaching a child to cook, and a book of recipes for somebody who already knows the basics of cooking and the kitchen but wants to know how to cook a particular thing. If you get teaching a child to cook mixed up with a book of recipes everybody concerned will have a bad time. It matters most for the child, they will never want to learn how to cook with you again. The same go for tutorials in my experience.

Angostura 7y ago

Good article. The division between different types of documentation is something that I've understood intuitively, but never codified in this way.

smush 7y ago

These 4 split ideas are great. I've previously maintained a wiki for our department and the most viewed documents are always shifting from year to year. Until now, I've never been confident enough to act on the bits of information I've gotten from people who said they liked X article because Y, and now I can see that those articles are a mish-mash of the how-to and technical reference. Now I will be able to use this as a framework for my continuing revisions, and be able to ensure that for any subject I want to be able to expect others to teach themselves to understand, I need to have the 4 quadrants ready to go. Sidenote: I loath the excuses I hear so much these days about self-documenting code obviating the need for __any__ documentation or code comments at all. I'm always looked at like I'm a woozle for pushing back on that. I can't decide if that POV comes from laziness or a sense of denial (this is fine) but that's a rant for another submission.

acidburnNSA 7y ago

Python developers: you can now make teaching tutorials in Jupyter notebooks and have them get automatically executed during the documentation build process and converted into theme-matching HTML by Sphinx with an extension [1]. I fired it up the other day and it's really glorious for tutorials. They're guaranteed to be up to date when you build the docs. Before that, I had a unit test that ran the tutorial with comments all over both the doc and the test that said YOU HAVE TO UPDATE THE OTHER IN SYNC! [1] https://nbsphinx.readthedocs.io/ https://nbsphinx.readthedocs.io/

AstralStorm 7y ago
Not just Python, Jupyter has plenty of backends. Including C++. Word of warning though, you might be tempted to use the tutorial prototype style for an actual application. That doesn't work in general.
closed 7y ago
nbsphinx is super handy! A cool tool to combine with it is jupytext, so you can keep your notebooks as rmarkdown files, which is a bit more human readable / GitHub editable. I did this with a recent library, siuba, and have not regretted it! https://github.com/machow/siuba/tree/master/docs https://github.com/machow/siuba/tree/master/docs

harimau777 7y ago

My experience has been that having names for things makes it easier to think and communicate about them; including in documentation. For example, once I learned the term "tail" I no longer had to say "every element except for the first one". As another example, learning about "complete" versus "partial" functions gave me the vocabulary to better understand and communicate about certain types of errors. Does anyone know of any resources that describe different types of useful vocabulary such as this?

andorov 7y ago
I think it is also useful to be aware of the specific terms your team might need and introduce words to those more abstract concepts. This frequently happens with naming specific code patterns or important classes in the code, but can also be for how the team operates in general. A DSL for how your team operates.
- LeonB 7y ago
  A glossary is a good thing to maintain. We keep one often updated in our wiki (at work)
arjenschat 7y ago
Being THE term is the holy grail for consumer brands. You can only get huge when your brand is the synonym for a whole concept or industry. Like ColaCola, Uber, Facebook, Tweet etc etc. For example Mark's explanation of Facebook [1] or the Photocopier sketch [2] Edit: fixed link order [1] https://youtu.be/cUNX3azkZyk?t=135 https://youtu.be/cUNX3azkZyk?t=135 (video) [2] https://www.youtube.com/watch?v=PZbqAMEwtOE https://www.youtube.com/watch?v=PZbqAMEwtOE (video)
- c22 7y ago
  You've got your hyperlinks on backwards.
agumonkey 7y ago
It's a bit of a generic issue. Until tail becomes a norm, it's hard to understand. I found embedded test/examples pretty great to quickly get the meaning of an idiom. in python for instance: def tail(l): ''' >>> tail([1,2,3]) >>> [2,3] >>> tail([]) >>> ValueException("undefined on []") ''' # actual logic

bryanrasmussen 7y ago

Well I know they never tell you we don't have any. which would be the truth most of the time.

commandlinefan 7y ago

What I’m always looking for with technical documentation - which I rarely if ever am able to find - is, what problem is this thing is trying to solve? How is, say, Angular better than plain-old Javascript? How is Spark better than a shell script triggered by a cron job? How is Spring better than Java by itself? What sorts of problems are they most appropriate for? Sometimes I suspect that I can’t find this information because there are no problems that this thing actually solves…

LeonB 7y ago
Agree. Comparisons (head to head) are a different category again. And hard to find (apart from as partisan sales pitches). Particularly useful if you know X and wondering if/why to consider Y. I often look at “alternativeto.net” to find products/services because we often choose things based on similarity and points of difference with things we already know.
uhoh-itsmaciek 7y ago
And how it's worse! It's extremely rare, but some projects do tell you, "If you need X, consider Project Y instead."
roelschroeven 7y ago
Webpages of many many projects do this very badly. I mostly resort to reading the corresponding wikipedia articles, if any, which often are clearer about what the project does and how it relates/compares to other projects.
- commandlinefan 7y ago
  > Webpages I've had hit or miss success even when I drop $50 on an O'Reilly book on the topic.
Crinus 7y ago
I'd generalize this with a "why". Why does this project exist? Why does that functionality exist? Why does it uses those types? etc (though you could say that this is part of the "Explanation" quadrant)

jrd259 7y ago

Two more categories of documentation: FAQ and trouble-shooting guide. Maybe you could call online chat-bots "documentation" (for trouble shooting or how-to?) but I've never seen one that actually did any good.

aasasd 7y ago

At last! I wanted to write something like this myself, only I identified two types so far: tutorials and reference. Lots of projects only have reference docs, some only have tutorials. Using one instead of the other is a pain. Having at least these two would be splendid for most projects. My ‘favorite’ example (in the bad sense of ‘favorite’) is Ansible, which had only tutorial docs for its YAML-based programming language―which they didn't want to recognize as a programming language. As a result, whenever I needed to look up some feature, I had to guess where in the tutorials it's likely to be introduced. Notably, plenty of important details are delivered as side notes sprinkled liberally all over the tutorial. (This was the situation with Ansible a couple years ago, something may have changed since.)

bordercases 7y ago
It would be cool to have a documentation style that embeds reference in the tutorial à la Tufte notes.

kaycebasques 7y ago

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 that shows how to use feature A, or vice versa.

franciscop 7y ago
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?
- carapace 7y ago
  *writer ;-P
- gautamsomani 7y ago
  https://www.linkedin.com/in/kaycebasques/ https://www.linkedin.com/in/kaycebasques/ This should help you :)

jpincheira 7y ago

Thanks for sharing this guide. It's fitting like a ring to finger as I am in the process of setting up documentation for the features of my app [1] because I realized that as an early-stage startup one of the best ways to teach your users how to use your product is by writing great documentation. I'm finishing the setup of this site within my landing now using Gatsby, on the main domain, so that it can also help to bring in more traffic from search engines. On the same topic, today I was listening to a podcast [2] titled "Getting traffic to a new website without blogging" which is excelent to match using Divio's guide. [1] https://standups.io https://standups.io [2] https://podcasts.apple.com/us/podcast/episode-344-getting-traffic-to-new-website-without/id656726654?i=1000451946117 https://podcasts.apple.com/us/podcast/episode-344-getting-tr...

zomglings 7y ago
Agreed. As someone making a very technical product, I can see how lack of documentation hinders my sales process -- potential customers want to try out my software, but the lack of documentation makes it difficult for them to overcome their inertia. As you did, I plan to spend the next couple of weeks just writing docs. Just want to lend weight to your comment. :) Thank you for posting the podcast.
- jpincheira 7y ago
  Seems we're both in the same boat! Exactly. If on live demos, they go like "wow, didn't know this case". That's exactly what you should go write after. I have a huge list of things to write about. Hope you enjoy the podcast, there are some gems there about SEO. Ruben Gamez —the person in the podcast— was also technical and learned his way around SEO. Mind sharing what your product is?
  - zomglings 7y ago
    Very happy to share - my co-founder and I started a company called Simiotics, where we offer metadata stores for data, preprocessing functions/transforms, machine learning models, and statistics. We also have tools that integrate with these metadata stores to automate work that most data science teams perform manually today - running preprocessing jobs, updating models in production, monitoring the distribution of data and predictions in production models, things like that. Our pitch is that, instead of having to do complicated things like set up an Airflow cluster, spin up a Kubernetes cluster and build helm charts, manage Spark, etc., a data scientist can just call out to our APIs from their Python programs (which may be running in notebooks), and we take care of the stuff they need to do but don't want to do. This is our website: http://simiotics.com http://simiotics.com These are our docs: http://docs.simiotics.com http://docs.simiotics.com (They are in a very sorry state, and it embarrasses us to post them here, but we are going to use that embarrassment to push us to make them better!)

kazinator 7y ago

> if the documentation is not good enough, people will not use it. Counterexamples: people use operating systems, web browsers, various "productivity apps" and games without reading a shred of documentation.

otterley 7y ago
Kubernetes... (although the documentation has gotten better over the years, to the project’s credit) Ruby on Rails as well, for the first few years of its existence.
- zomglings 7y ago
  I always found Kubernetes API reference very useful.
  - otterley 7y ago
    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.
    - kazinator 7y ago
      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.
ipsi 7y ago
Is that completely true, though? Almost all modern games include a (sometimes optional) tutorial, explaining the basics of how to play the game. Some number (a few? many? most?) of productivity apps will have in-app tutorials to get you up and running. Operating Systems... might have a tutorial? It's been a while sine I booted one up, and I'd likely skip it if present. On top of that, the GUI nature of these apps makes it easier to get started, I think, and even if there are _no_ tutorials, you can use your previous knowledge of similar apps and play around to understand it - click buttons, tap menus, etc, and learn by doing. I'm not sure where this fits into the documentation quadrant, but it's important, and is _why_ users can get away without reading documentation.

kissgyorgy 7y ago

Yes, there is a place where you can hear about those things: The Write The Docs community: https://www.writethedocs.org/ https://www.writethedocs.org/ (They also organize conferences every year.) It was really eye-opening when I visited a conference and heard those things the first time, it is highly recommended for everyone! https://www.writethedocs.org/conf/ https://www.writethedocs.org/conf/

zomglings 7y ago
Thanks. Did not know about writethedocs - that looks like a great community.

kozak 7y ago

Bad documentation covers obvious things very well, and doesn't cover tricky parts at all. This is especially what you get if the writer of the documentation is paid by the amount of written text: there is no incentive to spend time investigating the hard parts, but a lot of incentive to explain the easy parts in too much detail.

LeonB 7y ago

With reference docs, I really value the examples. Describing the syntax, in a formal way is necessary sure. But I often skip down to the examples and that way I get a feel for it quickly. Bonus points if the examples are thoughtful in the way they start with simple cases and move up to more complex ones while remaining practical and thus easy to imagine their usefulness.

ryanmccullagh 7y ago

Throughout my career as a software engineer, I've found myself reading source code to figure out how a piece of code works when there isn't sufficient documentation. As an example, writing a plugin for collectd is not very well documented IMO. So what does one do? Well, I know C, so I dove into the source code of collectd and was able to figure out how the API works.

sebastianconcpt 7y ago

The secret Documentation needs to include and be structured around its four different functions: tutorials, how-to guides, explanation and technical reference. Each of them requires a distinct mode of writing. People working with software need these four different kinds of documentation at different times, in different circumstances - so software usually needs them all. And documentation needs to be explicitly structured around them, and they all must be kept separate and distinct from each other.

luord 7y ago

As someone who might be adherent to "good code explains itself", this is a really great explanation of what documentation should actually be and how it should be organized. It's interesting how one of the projects that I for a long time have believed to have great docs is VueJS, and that documentation more or less adheres to these principles.

kerkeslager 7y ago

Some examples of what I consider to be good documentation: * RethinkDB * Stripe * Python

franciscop 7y ago

I am not sure if it's missing or it's part of one of these four, but another very important part for me is the introduction/README. Probably the most important one. Introductions include: - Project health indicators, all green. [tests | passing] and such. - Quick general description of the problem the project solves. - A simple code snippet showing how easy it is to use it. Not the most complex way of using it as many do, please. - Screenshots and gifs if it's UI-related. Very important if it's UI-related. - Quick installation guide if using a common way, or a link to an in-depth guide if it's not easy to install. - Links to other parts, in-depth articles, etc. Some examples where I think I got it right (feedback welcome!): https://github.com/franciscop/server https://github.com/franciscop/server https://github.com/franciscop/ola https://github.com/franciscop/ola That said, good documentation takes a lot of effort and time.

anaphor 7y ago
A great example of the simple code snippet is Flask https://palletsprojects.com/p/flask/ https://palletsprojects.com/p/flask/
pstuart 7y ago
> A simple code snippet showing... And the variable naming to make clear what is user vs. system defined.
qplex 7y ago
- One sentence describing what a project does (preferably the first sentence of a README)
swinglock 7y ago
franciscop/server > Powerful server for Node.js that just works so you can focus on your awesome project This is not a "quick general description of the problem the project solves" and I don't even know what the code does after reading this. You can do better than this.
- franciscop 7y ago
  Agreed, I haven't liked that line for a while. What about something like this? > A server for Node.js that works out of the box with modern Javascript It is a Node.js server with a bunch of middleware so that you don't need to do common things like body-parser, cookies, etc. It's also based around async/await instead of callback-based, which makes it easier to work with more modern JS and that prevents me from calling something like "express wrapper" or similar.

franciscop 7y ago

Good documentation IMO strongly depends on the project scope. There are many small projects that benefit from having a single, well structured long readme because it's easier to read+use. But there are some other projects that really need the longer format and everything described in this article.

slx26 7y ago

this is a great summary. I also like to add proper information about the context, the required knowledge to tackle each part, and the goal of that part of the documentation itself. in most cases, you can write a couple lines at the start of a document saying: "this document explains A. you will be interested on it if B. you should already know about C and D before proceeding. otherwise, you might be interested on E or F instead." I also noticed an interesting situation when trying to write good documentation: if you start too early, you will have to update it and change it a billion times (both writing the docs and testing the systems will reveal a lot of parts that can be improved). but if you start too late, everything will seem to be ok until you try to write it down. when you have done a few high-level overviews and detailed technical references, that always reveals how the are a number of important parts that could be simpler and/or more harmonic. we always try to make code simpler, but sometimes we only discover simpler ways to express things when we are thinking about them in natural language. or the other way around. perspective++

nlawalker 7y ago

docs.microsoft.com has a taxonomy that's a superset of this: overview, quickstart, tutorial, sample, concept, how-to, reference, resources. Most of the tables-of-contents are organized around this. Example: https://docs.microsoft.com/en-us/azure/app-service/ https://docs.microsoft.com/en-us/azure/app-service/

mark-r 7y ago
The only problem with Microsoft is that they delight in rearranging their web site. I'll bet that link is dead within a year.

peterwwillis 7y ago

There's more than four kinds; the main point should be that they need to be written with their particular purpose in mind. Here's some categories that apply just to system operations: - Reference - Discussion - Planning - Tutorial/Educational - How-To - Process Template (many, many kinds) - Process Implementation - Q&A There are also attributes: Local/Global, Draft, Approved, Certified, Published, Restricted, Versioned, etc. There's the venue: Internal, Customer-facing, Regulatory, Quality Assurance, Development, Managerial, Executive, etc. Then there's the scope of the document: high-level, deep dive, navigation, etc. When you write documentation, you must know your audience, what they need your document for, whether your document gives them everything they need, whether it's clear & concise, and whether anyone can find it when they need to. They should know when it was written & by whom, what it was written for, who it applies to. It should provide references to everything someone needs to know to make use of the doc. And not only should the document be clear, it has to stylistically express detail and make the document easier to process.

zackmorris 7y ago

I use lack of ambiguity as a measure of documentation quality. The best (honestly the only good) documentation that I've ever found is at: https://www.php.net/<keyword> https://www.php.net/<keyword> For example: https://www.php.net/echo https://www.php.net/echo Note how even this simple arbitrary example tells us "No additional newline is appended." It's shocking to me how many other guides would leave something that critical out of the manual. Then there are even helpful examples beneath that showcase users' experiences and any errata that they've discovered. Contrast this with Ruby's manual: https://docs.ruby-lang.org/en/master/ARGF.html#method-i-print https://docs.ruby-lang.org/en/master/ARGF.html#method-i-prin... I can infer that to_s is probably to_string. But I'm already hit with several new concepts like $, $_ and $\ which aren't clickable, so now it requires work to track down what they mean. The related methods beneath (like puts) are similarly cryptic. A good percentage of the time in search engine results, I click both the Ruby documentation and Stack Overflow links. I don't remember ever really learning PHP, because I realized quickly into it that it was a thin wrapper fixing any operating system shortfalls, generally leveraging concepts and contextual cues from C, C++ and the shell. Meanwhile Ruby had one of the steepest learning curves I've ever encountered outside of functional programming, even though it's similarly based on Perl and the shell. So where Ruby is a "convention over configuration" language, PHP is more of an "existing context over surprises" language. Writing the documentation for a language or framework can reveal these surprises, and over time, improve the tech itself and lead to a better experience.

alistproducer2 7y ago
I have to agree. Php is probably the easiest and moat productive languages I ever learned. The docs were great and the error messages always pointed me im the right direction very quickly. It's no surprise that the language caught on as it did. Ruby, by contrast seemed so hard to learn and I could never see what the advantage was over php so I never had the motivation to push past the difficulties of learning it.
degenerate 7y ago
Also a major overlooked factor in PHP's documentation success is having a specific URL for each function. Some documentation sites use #anchors to jump to spots in a document (ex: boostrap), but it's not good enough. What ends up happening is people search Google for something granular like "mysql concat" and end up on tutorial sites like w3schools. Why? Because the MySQL documentation throws CONCAT() into a giant messy page called "String Functions and Operators": https://dev.mysql.com/doc/refman/8.0/en/string-functions.html https://dev.mysql.com/doc/refman/8.0/en/string-functions.htm... Google "mysql concat" and see for yourself. Giant one-page docs are terrible. PHP got it right from the beginning.

mitchtbaum 7y ago

(great article, docs broke somewhere along the way) so do it while making the stuff especially once you reach the end, have it working, and are talking about it as if it's right in front of you do. it. then!.. don't wait till people are asking about it like it's recently forgotten.. even then, you're talking about it like it's in front of you; good docs time (point: repair broken links before breaking & appreciate and accept broken-ness as default, afair) (inside: i have a dream of a well-documented world) (point2: remember)

RcouF1uZ4gsC 7y ago

I think the zenith of reference documentation was the Windows API documentation on the MSDN CD's of the late 90's.

mark-r 7y ago
Absolutely agree, those were incredible. Looking things up on the web is a pale substitute.

devy 7y ago

I like the way the author use Quadrant Analysis (derived from Gartner's Magic Quadrants research methodology[1], well not exactly the same quardrants but similar way of thinking.) to explain the "right" way to do documentation. [1]: https://www.gartner.com/en/research/methodologies/magic-quadrants-research https://www.gartner.com/en/research/methodologies/magic-quad...

HugoDaniel 7y ago

I love the SQLite source code, it has a good ratio of comments per line of code

arminiusreturns 7y ago

I like this article, and if I may I'd like to add a more meta comment. In my experience, the biggest issue is getting people to use documentation systems in the first place. For example I have absolutely grown to hate confluence. Without plugins, and even with, it's a mess that becomes a barrier instead of a conductor. Therefor, for technical people, I think the best documentation tends to be easily accessible raw text. I personally use a combination of emacs org mode and asciidoc/asciidoctor. If I'm already always in emacs, why not use something already right there, and is quick and easy? The structure is important, but people just need to actually write the documentation in the first place. So, just write, and you will build the skills to differentiate types as the article refers to.

dredmorbius 7y ago

In my experience, it's explanations and how-to guides which are the most essential, with a comprehensive reference filling in the gaps. I've virtually always found tutorials almost completely useless. I also have a major gripe with the guidelines for how-to guides: these should explain things, most especially where: 1. Not following the process precisely, or appropriately to circumstances will lead to major issues. 2. Where the function, significance, or mechanism of a given step is critical to understanding and correctly applying the tool. 3. Where the reason(s) for choosing amongst a set of options is helpful in making that decision. One of the best concise distinctions between science and technology I've found is from John Stuart Mill: technology is the study of means, science is the study of causes or mechanisms. Technology tells you how and science explains why. Both are crucial to advanced understanding and use. This doesn't mean that a cookbook approach needs to have detailed "why" explanations, but it should at least touch on these. The other hugely useful aspect of a good cookbook is that it shows you the range of performance, capabilities, or applications of a tool. Readers can either hunt through for their specific problem (or something close enough to it to be adapted), or look through the range of applications to get new ideas for projects or products. One of the best cookbook texts I've ever encountered is O'Reilly's Unix Power Tools, first published in the early 1990s and still relevant. Kernighan & Pike's The UNIX Programming Environment is strongly similar, and despite dating from the 1980s, and being substantially obsolete in part, remains a valuable reference. Straight syntax guides, say, the Bash manpage, are useful, but are complex and difficult to navigate especially for a novice, and even a user with decades of experience. Tools such as vim and emacs share this problem, and whilst references can be useful for specific command or feature syntax and behaviour, do little to expose the power and capabilities of such tools. Cookbook approaches are far more useful.

bbanyc 7y ago

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 existed in print, with the troff source in /usr/doc but no obvious way to find it if you didn't know where to look. So naturally volume 2 fell by the wayside. When I was learning Unix in the late '90s and early '00s I had no idea there was supposed to be "official" documentation besides man pages, and filled in the gaps with random web tutorials and borrowed O'Reilly books and other "unofficial" sources. Nowadays some "Unix purists" are insisting that man pages are all the documentation you could ever possibly need, and if the man page is too long that means the software is too bloated. I find that attitude to be ahistorical. Like anyone's going to learn to effectively use troff and eqn from a cut-and-dried syntax description. (I could ramble a bit about the other documentation formats that have sprung up to replace troff and how, nice as they can be, they don't replace the convenience of manpages, but this comment is long enough.)

lliamander 7y ago
> The man command let you read all the pages in volume 1. Volume 2 only existed in print, with the troff source in /usr/doc but no obvious way to find it if you didn't know where to look. So naturally volume 2 fell by the wayside. I guess my feeling that man pages were insufficient is not without basis.
aasasd 7y ago
Notably, Linux had a whole lot of howtos and faqs—not sure about authoritative sources but I guess The Linux Documentation Project is/was the largest. That was how people learned to do stuff without tearing their hair out, in the early–mid-2000s. I probably still have some of them lying around thanks to stockpiling like the apocalypse is nigh. Of course, sparse or arcane documentation also leads to proliferation of educating books, by people ready to help for a reasonable sum. The existence of which market should say something about the truthfulness of ‘manpages are enough.’

adamcharnock 7y ago

I saw Daniele Procida talk at Commit Porto on this subject and it was very compelling to me. I’ve often lacked for a way to structure my documentation and this really resonated with me. I’ve since refactored and expanded documentation for one of my projects [1] to be in this format and I think it has resulted in something more more coherent. [1]: https://lightbus.org https://lightbus.org

quipquopro 7y ago