|
| 1 | ++++ |
| 2 | +title = "Documentation Best Practices" |
| 3 | +date = 2024-08-02 |
| 4 | +[taxonomies] |
| 5 | +authors = ["Hécate"] |
| 6 | +categories = ["Haddock"] |
| 7 | +tags = ["Practices"] |
| 8 | ++++ |
| 9 | + |
| 10 | +In the Haddock team, part of our mission is to help with writing documentation, and promoting best practices. This article will help you write the best documentation you can! |
| 11 | + |
| 12 | +<!-- more --> |
| 13 | + |
| 14 | +We adapt documentation outside practices to our ecosystem, and leverage our own technologies to empower Haskell users with their documentation work. |
| 15 | + |
| 16 | +Let us see some of these techniques, and how the Haddock team can be of help. |
| 17 | + |
| 18 | +## Writing documentation for your software project |
| 19 | + |
| 20 | +### Justify yourself |
| 21 | + |
| 22 | +When you create software, there is a pipeline from your brain straight to your code. Your decisions — such as the libraries you’ve used, |
| 23 | +or your program architecture — shape how your code is structured and written. |
| 24 | + |
| 25 | +Unfortunately, simply writing the code isn’t enough.The reasoning behind the decisions you made is as important as the decisions themselves. In the short term, solving a problem may let you move ahead immediately, but what keeps you on the correct path is understanding what |
| 26 | +brought you to that solution. |
| 27 | + |
| 28 | +Indeed, your choices may not be as popular as you think they are! Of course, you decided on them because you already convinced yourself |
| 29 | +that they’re best. But you have a user base to convince as well, and they may not see things the same way you do. |
| 30 | + |
| 31 | +As such, it is vitally important to document which decisions you made and to justify why you made them. If it’s not immediately obvious |
| 32 | +why a behaviour or a pattern exists, future maintainers might be tempted to drop it — only to discover too late why it was needed. |
| 33 | + |
| 34 | +### The reference flow of documentation |
| 35 | + |
| 36 | +Not all types of documentation have the same life cycle. Different pieces of documentation are more or less stable, and this determines |
| 37 | +which can act as a conceptual and theoretical foundation for your project. |
| 38 | + |
| 39 | +Examples of stable documentation include: |
| 40 | + |
| 41 | +* A README without code |
| 42 | +* A vision statement |
| 43 | +* The value proposition and the core domain |
| 44 | + |
| 45 | +These ought not to change much, because they describe the basic problems that your code aims to address, solve or support in the long run. |
| 46 | +While it is normal to fiddle around with the boundaries of your project at the beginning, in general these should change infrequently. |
| 47 | + |
| 48 | +Some other documentation is called volatile, like: |
| 49 | + |
| 50 | +* Documentation generated at runtime |
| 51 | +* Code examples |
| 52 | +* Tests |
| 53 | +* Configuration |
| 54 | + |
| 55 | +These are *expected* to change frequently, as your project changes, your API evolves, and you change configuration options. |
| 56 | +Volatile documentation is expensive to maintain, but also very valuable, as it shows in a concrete way how the user can interact with |
| 57 | +your project. |
| 58 | + |
| 59 | + |
| 60 | +> “When you refer to something, make sure the direction of the reference is from the more volatile to the more stable elements” |
| 61 | +> -- Cyrille Martraire, Living Documentation, 2019 |
| 62 | +
|
| 63 | + |
| 64 | +As such, here is a simplified model of the documentation cascade for a typical Haskell project, from the most volatile to the most stable |
| 65 | +sources: |
| 66 | + |
| 67 | +``` |
| 68 | +Haddocks of your library or a third-party library |
| 69 | +├──> Official specs for your domain |
| 70 | +├──> Architecture Document |
| 71 | +└─┬> Haddocks of a core library (base, text, vector, etc) |
| 72 | + ├──> GHC Manual |
| 73 | + ├──> Official specs for what the core libs provide |
| 74 | + └──> Papers (without paywalls) |
| 75 | +``` |
| 76 | + |
| 77 | +Keep in mind that while the Haddocks of a project can refer to the project specs, or to an architecture document, these documents should |
| 78 | +never refer to the project's current implementation. If you must refer to the code, point to where it's located. |
| 79 | +The (current, volatile) code cannot be the justification for the (planned, stable) architecture. |
| 80 | + |
| 81 | +The GHC manual is much more stable than the haddocks of a Core library, which is why documentation should flow from |
| 82 | +the library to the manual. |
| 83 | + |
| 84 | +Finally, papers serve the same purpose as architecture documents, where they describe techniques that may be implemented, |
| 85 | +but theyshould not point to code that is subject to change – lest they point to a library that has evolved so much |
| 86 | +that it no longer relates to the paper. |
| 87 | + |
| 88 | +#### Example: The Set data structure |
| 89 | + |
| 90 | +The [Haddocks for the `Set` datatype](https://hackage.haskell.org/package/containers-0.6.5.1/docs/Data-Set.html) |
| 91 | +(from the `containers` library) are an example of documentation which follows this model well: |
| 92 | + |
| 93 | +* They point to an overview of the API ([here](https://haskell-containers.readthedocs.io/en/latest/set.html): _volatile_) |
| 94 | +* They refer to the papers that have informed the design of its implementation: the absence of working links may be annoying, |
| 95 | +but the references can still be followed (_stable_) |
| 96 | + |
| 97 | +### Understand for whom you write |
| 98 | + |
| 99 | +This section introduces the Diátaxis Framework for documentation: |
| 100 | + |
| 101 | +<img src="https://diataxis.fr/_images/diataxis.png" width=100%> |
| 102 | + |
| 103 | +> -- Diátaxis Framework, by Daniele Procida, https://diataxis.fr |
| 104 | +
|
| 105 | + |
| 106 | +Diátaxis maps out the entire life cycle of one’s interaction with a system. Each of its four quadrants describes a different |
| 107 | +situation in which a user may find themselves. |
| 108 | + |
| 109 | + |
| 110 | +Diátaxis is not just about filling out all the quadrants like a checklist (although they are all good to have!). |
| 111 | +Instead, it is about understanding how each section focusses on a particular combination of user needs and situations. |
| 112 | +If a new user in need of actively acquiring some practice with the project, they can safely be pointed to the "Tutorials" part |
| 113 | +of your documentation, as it is the part that focuses on "_Acquisition_" of knowledge through "_Action_". |
| 114 | +The focus of the tutorial is to make a prospective user acquire basic competence in handling the software. It is an ice-breaker. |
| 115 | + |
| 116 | +However someone who is in need of a deeper – but perhaps less immediately applicable understanding of the project – |
| 117 | +will be better served by the Explanation, which serves the need for thought (or _Cognition_) |
| 118 | + |
| 119 | + |
| 120 | +In short, the message of Diátaxis is that you are not meant to write The One Documentation that covers everything — |
| 121 | +inevitably, this produces documentation which is shallow due to its breadth. Instead, focus on the strategic aspects of your documentation, |
| 122 | +and you will produce documentation of better quality, with a clear purpose that it can fulfill more easily. |
| 123 | + |
| 124 | +Through the lens of Diátaxis, the module API documentation produced by Haddock is a *Reference*. |
| 125 | + |
| 126 | +## Reach Out |
| 127 | + |
| 128 | +Should you need any help in writing or proof-reading documentation, please stop by the [Matrix chatroom](https://matrix.to/#/#haddock:matrix.org) of the Haddock team, |
| 129 | +or ping us with the [@haddock](https://gitlab.haskell.org/groups/haddock/-/group_members?sort=last_joined) group tag on the |
| 130 | +[Haskell Gitlab](https://gitlab.haskell.org/). We would be more than happy to lend you a hand and discuss how to best serve your users, |
| 131 | +you included. |
| 132 | + |
| 133 | +## Read More |
| 134 | + |
| 135 | +* [Haddock manual](https://haskell-haddock.readthedocs.io/latest/) |
| 136 | +* [The theory behind Diátaxis](https://diataxis.fr/theory/) |
| 137 | +* [How to contribute to Haddock](https://gitlab.haskell.org/ghc/ghc/-/blob/master/utils/haddock/CONTRIBUTING.md?ref_type=heads) |
0 commit comments