In writing technical articles in the Knowledge Base I try to adhere to certain principles and patterns, which I will attempt to justify here.
When it comes to technical writing, I follow this useful system of documentation classification summarized in this table:
Most of my articles are how-to guides. They tell you how to solve a problem or achieve a goal. They are not tutorials, or deep dive explanations, or references.
Respect the Reader's Time
- Articles How-To guides should have an introductory paragraph describing the problem and outline of the solution, allowing the reader to tell quickly if the article is relevant to them.
- No build-ups. Spill the beans quickly. Get to the good stuff as fast as reasonably possible, then "back up" in later paragraphs to fill in the details.
Liberal use of bullet points, which are easier to scan than dense paragraphs.
Expand title Diversions allowed, but hidden.. Sometimes a deep dive into a tangentially related topic is useful. Tangents are allowed, but should be hidden in an expanding macro, like this, or in a clearly distinct side panel.
Assume an advanced readership
Articles are aimed at an "advanced" administrator, who knows in general how Jira works, what a plugin is, has a vague understanding of SQL and databases. How-to articles are goal-oriented, not learning oriented; thus, for example, an article might state "run the following SQL" without describing how you are to load up, say, psql and connect it to your Jira database.
Full Size Screenshots
A pet peeve of mine is tiny screenshots. If a screenshot is important, I want to see it properly! Yes, it looks slightly amateurish having a giant screenshots embedded in a page, but that's too bad; aesthetics will have to take a back seat to readability.
...
Again, slightly cheesy but function over form.
Terminology
Plugins, not 'apps' or 'add-ons'
Originally Jira had 'plugins'. Then they were renamed 'add-ons' for a few years, and now they're called 'apps'. To quote Stephen Deutsch's explanation:
...