-
Notifications
You must be signed in to change notification settings - Fork 12
Writing Qi Docs
Qi's docs have some organizing principles guiding their design. Familiarity with them should help you improve the existing documentation and write great docs of your own. Of course, any docs are better than no docs, so adhering to these guidelines is a question of making a best effort, rather than a requirement.
If you're documenting a new component, ask yourself questions like these to help you decide which sections of the docs need updating:
- Is this relevant to beginners? (Introduction, or perhaps the Tutorial?)
- Does this component give rise to new errors? (Update the list of commonly encountered errors)
- Is there any practical advice I could give in connection with this new component? (Field guide)
- Are there any underlying principles that would be worth elaborating on? (Principles of Qi)
- Does this provide another reason to or context in which to use Qi? (When Should I use Qi?)
- Could this cause confusion in some situations? (Gotchas)
- Does this add any new forms to the language or modify existing forms? (The Qi Language)
- Does this add any new ways to use Qi from the host language, or provide any other interconnects between languages? (Language Interface)
- Does this help people write Qi (Input Methods)
- Does this have anything to do with extending Qi with macros (Qi Macros)
If the component warrants an entirely new page or top level section in the docs, be sure to signpost the purpose of this section in "Using these Docs."
Every need that a user has is fielded at a surface-level entry point. E.g. "I want to know how X works" or "I'm having Y problem". The docs attempt to anticipate these needs and have dedicated sections to receive these users.
At the point where the need is fielded, there is typically a self-contained resolution, although it may link to other places in the docs in providing the answer.
Where useful, the documentation signals relevance to the reader. In this way, the documentation captures not just what the authors know about the thing being documented, but also what they know about the documentation itself. This may include leading with some indication of relevance ("If you are trying to do X, then ...") and may also involve pointing the reader to other relevant sections of the documentation, typically with some annotations as to why those other sections may be relevant or interesting. Context-sensitive and signposted organization allows all the information to be present without burdening the reader with irrelevant things.
The "self-contained resolution" principle means that the same topic may be discussed in different sections of the docs in different contexts. The principle of "topological connectedness" is that all of these sections should be linked to one another -- that is, there should be at least one link-based path that forms a full cycle over each of these sections, without the reader having to leave these sections. This serves two goals: (1) The reader can easily find all documentation on the topic in a guided way without it needing to all be in one place, and (2) it makes the documentation easier to maintain for developers, since we too can easily find all related docs when they need to be updated.
In code, we often don't want to say the same thing more than once. But with documentation, it aids the reader to say the same thing many times in different ways and in different contexts. However, the docs avoid saying the same thing the same way more than once.
The documentation for a feature explains what the feature is (e.g. "switch is a predicate-based conditional form"), how it works (e.g. "Each of the predicate and consequent clauses is a flow that receives all of the inputs as arguments"), and why it matters (e.g. "switch is useful to express conditional transformations, where it can eliminate redundant mentions of the inputs.").
In addition to explaining how features may be used, the docs also attempt to provide insight into them to help the user have a clear understanding. The documentation should in principle contain everything that could be of interest to any level of user -- but not all in one place, as described in "Topological Connectedness," and some of this information may take the form of external links.
In the spirit of saying the same thing more than once in different ways, the principles above can also be seen in another light, which is that they allow the documentation to be context-specific while still being general -- goals which may seem contradictory. For instance, one way to document a particular feature would be to have all of its docs in one place, with general information that could be specialized to any usecase. This would ensure that it's comprehensive but not as helpful as it could be. Another way is for these docs to include advice that's relevant in every conceivable context. This too is comprehensive, but the drawback is that it could lead to information overload, and more importantly, to inefficiency in handling the user's needs. If there is a way for us to know why the user came to the docs (which can be accomplished by the "fielding user needs" principle), then why not solve their particular problem? Said yet another way, structuring the docs in this way allows the docs to have more information about the user's needs, allowing it to make informed, rather than context-free, recommendations.
When it comes to tone and style, consistency is valuable, but a good result is better than a consistent result.
Qi's docs are inspired by Django documentation from the python world. This talk by Jacob Kaplan-Moss, one of its main authors (and of Django itself), is great -- required viewing for anyone serious about writing great docs.
Home | Developer's Guide | Calendar | Events | Projects | Meeting Notes