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?
Conceptual overviews
Four kinds of documentation
61–70 of 203 posts
Re: Four kinds of documentation
#62At 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.)
Re: Four kinds of documentation
#63Earlier quoted context omitted.
A separate specification works much better as long as that specification is also enforced during the build. A separate openapi spec that is not enforced can quickly become outdated, then an auto-generated from code is better.
You can add two new columns to your Kanban board called "Documentation" and "Documentation Review". Then tasks cannot move to your "Done" column unless documentation is written and passes review. If you enforce column limits documentation it will also block other tasks if not completed.
In addition to this (and going a bit off topic). I've been adding checklists to Github PR templates (it's really easy[1]) for things like, "Did you re-read the relevant API docs? Do they need to be changed?" and it helps me a ton.
[1] https://help.github.com/en/articles/creating-a-pull-request-...
Re: Four kinds of documentation
#64As 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.
Re: Four kinds of documentation
#65Thanks 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.
[2] https://podcasts.apple.com/us/podcast/episode-344-getting-tr...
Re: Four kinds of documentation
#66At 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 lan…
It would be cool to have a documentation style that embeds reference in the tutorial à la Tufte notes.
Re: Four kinds of documentation
#67My 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 kn…
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 (video) [2] https://www.youtube.com/watch?v=PZbqAMEwtOE (video)
You've got your hyperlinks on backwards.
Re: Four kinds of documentation
#68Earlier quoted context omitted.
I do not share your experience, because in my experience the auto-generated docs will be kept in sync with the code/API while a separate specification will become outdated over time. This does of course require human-readable description in all the endpoints. But that's the same as only an autogenerated function signature in code documentation vs an added human-readable description.
> I do not share your experience, because in my experience the auto-generated docs will be kept in sync with the code/API while a separate specification will become outdated over time. Does it? You can just alter the code and forget to alter the documentation above the functions/methods, so I don't think there is much of a difference. And wrong documentation is worse then no documentation. You have to write your docu…
With Rust, we help mitigate this by running code examples in API documentation as tests. That doesn't stop people from opting out, and it doesn't solve every problem, but it's still quite useful!
Re: Four kinds of documentation
#69> 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.
Re: Four kinds of documentation
#70Yes, there is a place where you can hear about those things: The Write The Docs community: 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/