💾 Archived View for posixcafe.org › blogs › docs.gem captured on 2022-06-11 at 20:51:37. Gemini links have been rewritten to link to archived content

-=-=-=-=-=-=-

Docs save lives

I've recently been trying my hand in some areas of tech I have sworn off, not due to a change of heart, but to wanting to understand more of the discipline as a whole. Being a fairly new programmer in these foreign waters, I have realized how often certain domain knowledge is taken for granted and overall issue with the ways in which libraries document their usage.

In my eyes the documentation of a library has the following responsibilities:

Communicate the control flow that the library expects
Displays and describes all of the tools that that the library gives the programmer
Communicates limitations of the library up front to the programmer.

For some common anti-patterns that violate one of these:

Documentation that is just examples, lacks requirement 2 and 3 and becomes a pain in figuring out use cases outside of the given scenario
Documentation that is just type signatures and brief docs for each, this lacks points 1 and most often time point 3 and thus becomes a pain to figure out how the user is expected to compose the functions together in their own function.

The third responsibility is a tricky one, as I feel that in our feature driven tech culture at the moment it is seen as a weakness to admit that your tech is not fit for a given task. However within a project you will find a myriad of developers willing to say "this is not how you do X, we do not support this do this method Y". So my question becomes why not extend this awareness to the library as a whole? I applaud a library that is quick to tell you that they are only useful for a specific subset of problems and nothing more. This attitude keeps the weight down and allows for other more specific libraries to be used in other use cases. It saves the trouble of the developer learning a system that ultimately is a poor fit for their problem space. Be the first one to admit known issues or limitations of your own code, it saves the rest of us a lot of time when dealing with it. For an example of this done right look at the DIAGNOSTICS/BUGS section of common 9front manual pages.

Now of course there are some exceptions here, sufficiently small libraries can get away with small amounts of documentation. This being of course that small libraries can act more like code snippet examples to the developer and it is often much easier to simply read the code and understand it from there. I am also not against the programmer diving in to the library to learn the reasoning of why some limitations exist, but I don't think that is how they should be finding out about them in the first place. Libraries should have a high level of 'fly by' information for those who are shopping for which library to use, just enough to outline what the use case of the library are and some design limitations of it.

Another huge benefit of laying out your limitations is that it communicates to the programmer what issues are known, which issues are known and part of the design and which are not known and not part of the design decision. This can reduce confusion and keep the flow of new issues coming in a bit more meaningful. Save me the trouble of me trying to fit a square peg in to a triangle hole, and yourself the trouble of having to sift through bad bug reports.