You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

In writing technical articles I try to adhere to certain principles and patterns, which I will attempt to justify here.

Respect the Reader's Time

  • Articles 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.

    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.

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.

To distinguish large screenshots from the rest of the page, you will notice extensive use of the drop-shadow effect, e.g.:

Again, slightly cheesy but function over form.

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:

Just to add to this, originally plugin was the term for a piece of software that extended the functionality of server products, as it is a piece of software written in Java that is installed inside of the host product (Jira, Confluence, etc.).

When this functionality was brought to Confluence Cloud via Atlassian Connect, the software that extended the functionality existed on another server in any language, so the term plugin didn't make as much sense in that context. That's why they decided to use the term add-on.

Finally, in order to unify the naming convention (as well as introduce terms that many consumers were already used to like app and appstore), they decided to change the term for any piece of software that extended functionality to be called an app. This change was made around August of 2017: https://community.developer.atlassian.com/t/marketplace-now-has-apps/7524

Whether that's a good thing or not is a separate discussion...

Articles on this site I work mostly with Jira Server, where 'plugin' is the original term. Unlike 'app', 'plugin' correctly denotes the embedded, subordinate, extending nature of the extension. Thus, I will stick to 'plugin' while Server is my preferred platform.

  • No labels