Four kinds of documentation
divio.com
divio.com
- 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/ola
That said, good documentation takes a lot of effort and time.
And the variable naming to make clear what is user vs. system defined.
> 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.
> 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.
Is it a web server, a web framework, a PBX, telnet or general TCP, UDP or Unix socket support functions? Which protocols does it run? Is it a library? Is it a daemon?
It says so little, it could be literally anything.
I guess it has something to do with HTTP and I guess it's a library/framework because I guess a web developer wrote this, but only because it mentions JavaScript and doesn't specify further. But these are still just guesses, I wouldn't know from the text alone.
> works out of the box with modern Javascript
Does it work with other languages too, just not out of the box? If not, the "out of the box" doesn't add anything here. Doesn't similar code work out of the box anyway?
No, very notably both Express and its modern counterpart Koa don't work out of the box and devs using them have to learn, install and configure quite a few packages (middleware). This includes common functions like parsing the body of an HTTP request, parsing cookies, etc. This is the reason I created `server` in the first place, to do `npm install server` and not worry about these things on a per-project basis :)
Thanks for all the feedback, I'll replace "server" for "webserver" in my previous sentence. That alone is a great improvement over the current text IMHO.
> A server for Node.js that works out of the box with modern Javascript
Just give me the more verbose, but more conversational, explanation.
> 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.
Sure it's more words, but I didn't have to think as much :)
What your thing looks to be is a wrapper over Node's `http` module, with a simplified API. "Powerful" is really not an appropriate adjective, since obviously your lib is limited to what the underlying Node's http module can do (and I'm going to go on a limb and guess that your library doesn't natively handle things like streaming or chunking or UPGRADE for web sockets or HTTP/2 push or N number of other things, considering you claim the library is also "simple").
These suggestions generally correspond to document sections within the Linux Documentation Project HOWTOs, as an example.
If it's a UI toolkit, I'm not going to download, grab dependencies, and compile it, mock up a basic app just to find out it's the not something I want.
Came here to say/reiterate this. A README is very flexible and can be any of the four types, the decision of which will depend on the contents of the repository and on what the README is trying to accomplish.
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.
Instead, we often get nothing but a method name and argument types. Ridiculous.
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-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.
I laughed and then I got sad
I've actually written some pretty long comments on reddit. Yesterday, I talked with one of my coaches and put some thought into why:
1) I don't have any memories of feeling anxiousness from commenting on reddit. This is unsurprising since it has never been assigned to me by a teacher/parent. If I ever feel like "Its unclear why I would respond to this or what I would say to this", I just choose not to comment.
2) I have memories of writing a comment and other people upvoting it or telling me that it was helpful. I don't have this for essays. I driven by making people happy, so that is a meaningful reward.
3) Because of those positive memories, as I am writing, I can imagine that a sentence I am about to write is going to be helpful. That imagining is a bit of positive re-enforcement that I can chase, inherent to the task. It is like when I was a kid and I would do math homework and I would solve a problem and see that I'd solved it. It is one of the tricks of TDD.
So, my plan this Saturday is to seek out the things that could possibly be intrinsically rewarding about writing:
A) Look for interesting phrases that I can craft to clearly explain something.
B) When I start on a section, write a question that someone could ask on a reddit thread, which this section answers.
C) When I write a section, imagine myself saying this as an explanation in response to that question and imagine someone else expressing gratitude for that explanation.
D) To avoid procrastination, mentally rehearse the act of starting and getting into the task. Simulate the trigger-response-reward in my mind so I can build the neural pathway. The reward I imagine should not be tied to completion, but come from the "I've just gotten started" state.
Sure, if documentation is treated as an afterthought it tends to reflect that attitude.
Bingo.
Do note that people here on HN live in a bubble where, for example, writing tests (any tests, not even good tests) is a given. But out there in the world there's plenty of software coding, a lot of it in major companies, where developers think testing is some cute but useless thing they teach you in college and which can be safely skipped, and managers are completely oblivious about this. Same with writing useful documentation.
For documentation to remain relevant there needs to be some kind of process actually checking every part of it against reality.
I mean, with actual code you get some help from the tools. No silver bullet, but at least you have type checks, compiler errors, something. But with docs there's no way to automate checks to see if the doc is still relevant and accurate. And what terrible tools are there tend to lead to "boilerplate docs", like those javadocs mentioned in a comment elsewhere.
I've been wanting some kind of system to add references to tests to documentation, in the spirit of citation. Maybe I will build it at some point.
Because those who control resources make a conscious decision to prioritize new features and/or bug fixes rather than documenting what exists already.
The problem comes months later when I'm in the weeds and a colleague asks a question. I try to fob them off to the documentation, but some details are out of date. I pray it's just one detail, and that I don't have to stop what I'm doing to rewrite the documentation now.
# <PROJECT NAME> Service
This is the new service for <TASK>.
....I could buy a good README.
Good documentation, enabling user self-support, eats both cost and revenue.
(To what extent this is a conscious strategey and not simply decades-of-experience-born cynicism, I'm not entirely sure.)
Now if you use human language to document your functions (methods) that is not a problem, but too often I see something like:
public class BookStore {
...
/**
* @param book The book.
* @return The price.
*/
public static float getPrice(Book book) {
return book.price()
}
}
Maybe "auto-collected" is a better term for this than "auto-generated". I agree that auto-generated docs almost by definition don't add much. But if you go in and write narrative and have it get nicely collected into a slick hyperlinked webpage by things like doxygen and Sphinx, then that's great.
There should be a roadmap somewhere as well, possibly in a Wiki or the developer docs.
Of course, the other side of this coin is that without these draconian build processes I probably wouldn't write the useful kinds of javadocs I write for significant methods.
Not a contrived example. There are an absurd amount of libraries that do this and call it documentation. There will be a nice, tidy example of how to use the library with a toy example. That's fine. The intro probably doesn't need to go that deep. Then I move to the technical documentation or API, and that's what they have to offer.
y++; // Bump y
y++; // Do we need error checking for top of y axis?It is a completely different situation from the lack of such a comment, that implies that the author didn't stop to consider the function, and you can find any kind of strange things when calling it.
Docs generated from code do not define the contract, they describe the code-defined contract, bugs, accidental mutations, and all. How is that not a fatal flaw?
A separate openapi spec that is not enforced can quickly become outdated, then an auto-generated from code is better.
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.
[1] https://help.github.com/en/articles/creating-a-pull-request-...
I keep hearing swagger / contract first. But then they still manually specify `/api/v1/user/login`.
Vertx web api contract router. Which takes in a swagger file, and routes based on the `swagger` operation id. Is the closet I've seen. https://vertx.io/docs/vertx-web-api-contract/kotlin
I've also written a library to route into ktor in a type safe way.
But if you're doing swagger. To me it should be written, then consumed by the back-end service. Then generate front-end clients. Anything less will result in bugs.
I've seen companies pile on so many services. To double check code generated swagger. Hit a bug, then have to maintain the swagger spec outside and not enforce it.
less code, standard approach, less bugs.
This is an option, but I find that it works better to have OAS documents generated from what the server is actually doing. Specifying routes based on what the server actually does is, IMO, a more rigorous way to create an OAS spec than to hand-write the spec and then generate a server from it.
I've written a couple of libraries that do exactly this:
https://github.com/eropple/nestjs-openapi3 - OpenAPI3 library for NestJS that standardizes input validation
https://github.com/modern-project/modern-ruby - a Ruby web framework built around OAS3 concepts + rigorous validation
If I'm a consumer of some third-party API, there's no practical difference between intended behavior, accidental mutation and a bug which the supplier won't fix any time soon - all of these things are equally part of the contract of how The Thing v1.2.3 works, and that's what I want described in the documentation. Any part of the documentation that says what The Thing should do (but doesn't actually do) is worse than useless, it's actively misleading; it describes some wishful thinking with no connection to reality.
If the contract documentation describes an interface between two parts of the system that I control, and I have the ability to fix discrepancies between contract and code by altering the code, then sure, that's a different situation; but if I don't have the ability to make these changes because it's an API to code made, maintained and controlled by someone else, then accurately describing current reality is the most important thing.
Likewise if v1.2.3 has a bug I want to know to not rely on that because I'll probably update to 1.2.4 which fixes it.
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.
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 documentation, keep it up to date and take it seriously. I would argue, if you have auto-documentation you are more likely to miss that, because you have some kind of documentation somehow - irregardless if it's actually useful.
If I'm looking at documentation, I want the inputs and outputs and a brief description of what it does. I care very little about the implementation, or I would write my own.
Rust for example also warns about code included in the doc comments example section which is invalid.
Then it just takes some self-control and gold code reviews to make sure you're writing good documentation rather than just short stubs to silence the error.
It checks for rust snippets in markdown files and attempts to build them when you run `cargo test`. It helps keep docs and code in sync.
Yes you can forget, but the barrier is much, much, much lower than having to modify a document god knows where.
And every other modern language, be it statically typed or dynamic (with the help of annotations), has had some sort of auto-documentation generator either bundled or at package manager's reach, and probably any can top javadoc in many ways.
The frustration pointed out by OP is that when you see a page of "blank" generated documentation you never know if there is valuable information waiting for you maybe just one or two clicks away or if it's placeholders all the way down. Consuming a sparsely filled doc almost feels like being trapped in an illustration of the halting problem.
A javadoc/-like implementation that somehow put the actually authored subset into the spotlight while not completely skipping the inferred bits could be very valuable.
(also: a javadoc/-like compiler that detects as much delegation as possible and aggressively pulls in stronger documentation when it is available further up or down the call nesting)
Still better than 90% of projects/libs at the time, who didn't have any reference documentation at all.
Just seeing the signatures and packages in an organized manner with cross links (e.g. to parent class, implementing classes) etc, was a vast improvement...
In Hoogle, I can type `Map k v -> (v -> Bool) -> Map k v` into the search bar, and it finds the function, even though I got the order of the arguments wrong.
https://hoogle.haskell.org/?hoogle=Map%20k%20v%20-%3E%20(v%2...
When you're looking for functions, do you generally use Hoogle, or do you have a local autocomplete-like feature hooked in to your editor? I really want to be able to use this while writing code.
Pure languages get a lot of hate, but this is the kind of thing you get when you enable better static analysis of your code.
This is something I think rustdoc (for rust) also has succeeded at, partially for similar reasons.
It's been the better part of a decade, so I can't actually quote correct APIs, but I recall trying to connect to an LDAP server - I just needed to call one of four constructor methods, which seemed to imply I needed an LDAPContext object. Looking at that object told me the 10 bajillion values it had, but no idea how to set them.
Once I saw an _Example_, which IIRC was basically calling a method to clone the default context object and setting the one or two params (such as server url), I could then pass that to one of the constructors I saw the docs for.
The generated documentation was 100% _correct_, but not _useful_.
Other languages I had been in had very example-focused documentation, and were far more accessible and usable as a result, even with occasional challenges where the docs might slip behind - that almost always tended to be corner cases, while the Java approach made the most common need into a corner case.
Especially in the enterprise world, I often come across completely useless code docs, created purely to satisfy SonarCloud or an otherwise stupidly dogmatic gated checkin of the "all public methods must have code docs!" variety. I'm sure many of us have come across it - code docs for a constructor that say "Constructs a Widget", or for an `AddWidget` method that says "Adds a Widget"; utterly pointless. I think of this as "dogma driven documentation".
Even if you have great inline documentation that can be turned into a great external reference document, you need separate documentation.
... Hi, I reaching out to to ask if I could get my hands on some documentation because the API is somewhat a black box to me.
... The api documentation for [product] can be found here: https://api.[product].com/
... Sorry. That's not what I mean by "documentation". It's certainly non-linear. I don't know how to "read" this site to gain an understanding. It's kinda sparse:
GET /v2/adjustments > Implementation Notes: Fetches a list of adjustments.
GET /v2/reportCategories > Implementation Notes: Fetches a list of report categories.
... "Swagger Documentation" is a special class of documentation for sure; Nobody likes writing documentation.
Talk about insider (them)/outsider (me).
If you need to add data to one endpoint and see how that travels to other endpoints, that makes sense as to why you want documentation. In that case, a product / API tutorial or recipe (like the author suggests) might be useful.
This from the Rust standard library is a good example - https://doc.rust-lang.org/std/result/index.html . I think that's great documentation, and it's entirely generated from the source code.
Most rust libraries won't have this level of explanatory detail, the core team have put a lot of effort into making it as easy as possible to learn, and documentation effort is part of that (the Rust book is another important part).
Something else that Rust does well is that 'examples' is a standard part of project layout. For libraries that haven't done their top level documentation well, the examples folder will usually give a good demonstration of how to use the code, and they usually exist because that's the easiest thing for the library author, and the usually compile because they're automatically built by `cargo build`.
For most applications this approach is generally useless and should not be used. Comments should be in the code itself, and you expect people who want to work on the application to read at least some of the code. I.e. no reference / API documentation for applications, instead high level overview (where is what, application architecture etc.) and guides (how to set up your dev environment, how to contribute, how to prepare releases etc.).
For libraries it often makes sense to generate a reference documentation from the code itself. The drawback is that the strictly formulaic nature of comments parsed by the documentation generator has to be always kept in mind when writing the code itself. I.e. the comments need to make sense and be comprehensive when you remove them from the code surrounding them.
Some modules in the Python standard library are a good example of this. Quite a large amount of prose, separate from the code, and then a reference section generated from code. However, many modules have pretty bad documentation, where even the reference is missing crucial information (quite often very basic things like what a function returns).
Rust handles this nicely; its generated docs are based off source code comments. Same with Golang.
Why do you think it's useless? What part is useless? I am considering taking on this project at some point in the future.
Edit: also I am referring to a library's API while I think you refer to a RESTful API. Would your comment also apply to libraries's API?
Just like you can write bad code, you can write bad docs, not update them etc.
The point of code generated documentation is not to render the interfaces but rather to keep code and docs in sync in the same place. It's more likely you'll se an out of sync / undocumented piece during a code review, in context, etc. then to assume it was updated somewhere else.
Many people hate auto-generated API documentation because library authors do not write enough of it.
For example here are my project's auto-generated documentation from source code, for two classes:
https://gojs.net/latest/api/symbols/Diagram.html
https://gojs.net/latest/api/symbols/GraphObject.html
That's 1238 words and 1408 words before you even get to the constructor.
There should be a lot of information that comes out of the auto-generated API: What it is, what to know, different kinds of classes interact, and where to go next.
Then of course a primary tutorial: https://gojs.net/latest/learn/index.html
And then conceptual Intro pages: https://gojs.net/latest/intro/index.html (62 of them, covering everything from high level concepts to printing)
Then, since so many people learn by example, hundreds of samples, organized with pictures and tags for each, with an explanation and commented code: https://gojs.net/latest/samples/index.html
Unfortunately, in my experience a lot of devs turn on auto docs in their project's settings and call it a day, especially if it's not a library/API!
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.)
I guess my feeling that man pages were insufficient is not without basis.
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.’
Looks like this one: https://wolfram.schneider.org/bsd/7thEdManVol2/
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.
Also I'm curious, how do you become a technical writter? Does it involve writing articles/blogposts/etc to promote the project?
;-P
This should help you :)
For example:
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-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.
Google "mysql concat" and see for yourself. Giant one-page docs are terrible. PHP got it right from the beginning.
Which also results in each function having its own comment section, where users can post further examples and pitfalls with that function. These often end up significantly larger and more informative than StackOverflow.
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.
I've had hit or miss success even when I drop $50 on an O'Reilly book on the topic.
(though you could say that this is part of the "Explanation" quadrant)
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/
[2] https://www.utwente.nl/en/bms/ist/minimalism/displaywriter.p... (PDF)
* 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.
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.
Word of warning though, you might be tempted to use the tutorial prototype style for an actual application. That doesn't work in general.
I did this with a recent library, siuba, and have not regretted it!
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...
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.
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?
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
These are our docs: 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!)
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?
Edit: fixed link order
[1] https://youtu.be/cUNX3azkZyk?t=135 (video)
[2] https://www.youtube.com/watch?v=PZbqAMEwtOE (video)
in python for instance:
def tail(l):
'''
>>> tail([1,2,3])
>>> [2,3]
>>> tail([])
>>> ValueException("undefined on []")
'''
# actual logicI'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.
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.)
Counterexamples: people use operating systems, web browsers, various "productivity apps" and games without reading a shred of documentation.
Ruby on Rails as well, for the first few years of its existence.
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.
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.
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.
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++
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/
[1]: https://www.gartner.com/en/research/methodologies/magic-quad...
- Reference
- Discussion
- Planning
- Tutorial/Educational
- How-To
- Process Template (many, many kinds)
- Process Implementation
- Q&A
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.
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.
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.
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.
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)
[1]: https://lightbus.org
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.
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-we... (2013)
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.
You might be right but I don't remember being impressed with Microsoft's documentation. Half the time if was missing APIs for common useful tasks (there was a big community around demoing undocumented APIs -- granted some were genuinely only intended for internal use but there were some APIs that really should have been documented but weren't) and some of the example code Microsoft did publish was next to useless.
There was one occasion when I was teaching myself DDE (anyone else remember that?) and the example looked a bit weird because the example application would launch and call itself. "ok," I thought, "I'm obviously missing some logic when reading through. Maybe I should just run it to test it's behaviour." Five minutes later I was forced to reboot after my suspicions were confirmed -- their official DDE example was literally just a fork bomb. Well done Microsoft /s
However I did learn a valuable lesson that day: never trust example code.
But ever since 3.1 docs you could learn everything you wanted from the help file alone (3.0 help files were reference only) and i mainly refer to their structure. The content was sometimes a miss (though the worst i can remember is not being sure how region object lifetime was managed since unlike other GDI objects there wasn't any function to delete it).
Do you know if there's a way to access info documentation in a PDF reader (or failing that a browser)? I often try to read the info pages then quickly give up because I don't want to fuss with the navigation. I would love to be able to say `info --format=pdf --open-with=evince sed`. Is anything like that possible?
EDIT: Another cool approach that would preserve hyperlinks would be a command that starts a local web server on say 4400 and launches firefox on its index.html.
However note that the "source documentation system" i refer to is texinfo, not info. Texinfo is a preprocessor and documentation language (think docbook) for manuals that produces a bunch of formats, one of them being info, a text-only hypertext format (which was one of the earliest hypertext formats AFAICT). GNU info is a viewer for that format, but there are others, however all of them just view info files and have its inherent limitations (e.g. preformatted text, links using a rigid syntax, etc) - though also they have benefits such as support for topic keywords, indices, etc.
Texinfo can also be converted to other formats like PDF (through tex - i guess the initial version generated only tex and info output, thus the name texinfo) and HTML. So you wont be using texinfo to view info as PDF files, but you'd be using it to generate PDF (via tex).
I guess the "texinfo" and "info" names can be confusing and make people think that they are the same thing - the fact that AFAIK texinfo is the only info file generator (and that GNU info is called just "info" which is the same as the file format name) doesn't help :-P.
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/ - 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 - 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 - 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/ - 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/ - 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 - 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.
* RethinkDB
* Stripe
* Python
"Explanation - Topic" sounds a bit wonky as a section/title. Does anyone have a suggestion what to call those types of articles?