Posted on December 5, 2017 by Troels Henriksen

We have the vain hope that, some day, Futhark will be more than just a vehicle for writing research papers about compiler optimisations. However, if we want our work to be useful in practice, it is not enough to simply write an optimising compiler - we also need to write comprehensive documentation so people know how to use it! I have no illusions about the Futhark team being intrinsically gifted documentation writers, and our team is furthermore so small that we need to maximise the return on our time investment. One way to do so is to look at how other programming languages manage their documentation. One language that we often look to for inspiration is Rust, as they tend to make good decisions.

However, merely cargo-culting Rust would not be very satisfying. We would also like to understand the essential purposes of documentation, so that our efforts can be more focused. Fortunately, Daniele Procida already wrote an article on the subject, titled What nobody tells you about documentation, where he characterises documentation by four different functions: tutorials, how-tos, explanations, and references. While there is plenty of room to disagree with this model (personally, I’d say there is apparently a need for some theory explaining why light grey text on a white background is a terrible idea), it seems a useful starting point to thinking about documentation in a structured way.

To expand a little, the four functions and their orientations, are:

Tutorials

Learning-oriented and targeted at beginning users who do not yet even know what to learn, or which questions to ask. A tutorial needs to hold the hand of the user and show them something they have not seen before.

How-to guides

This is goal-oriented documentation sought out by users who already know what they want to accomplish, but not how to do it.

References

Information-oriented documentation that describes machinery in detail, but without focusing on specific uses. Accuracy and coverage is paramount.

Explanations

Understanding-oriented, in-depth documentation that focuses on background, context, and theory.

For Futhark, the user's guide provides a decent reference on how the language and compilers work, but it does not (and should not) fulfil the role of tutorial, how-to guide, or explanation. Instead, some of these roles should be filled by the in-progress book, Parallel Programming in Futhark. In particular, if we model its structure on the Rust book, it seems like it will essentially consist of repeated switching between tutorial and explanation segments. Intuitively, this also seems like a good structure: first describe something concrete (“here is how to use map ”), followed by deeper reflection on what map is (such as an introduction to parallel cost models, or the fusion optimisation). In fact, such a refactoring of the book would solve one of the problems with its current form, which consists essentially of a verbose language reference, followed by a handful of chapters on the theory of data parallelism. These chapters contain useful information, but they are currently too detached from the discussion about the language itself.

The structure outlined above still leaves one documentation function unaddressed: how-to guides. These can be written in the form of appendices tacked onto either the book or the user’s guide, or perhaps even as an extended FAQ on this very website.