Documentation

Aka documentation style guide, write documentation

Write all, make reports, about choice has been mades

Conciseness

API references, guides, tutorials, and blog posts

Writers should value their readers' time — and always try to get to the point.

The only thing worse than no documentation is incorrect documentation, because no documentation means I go somewhere else to look for it. Incorrect documentation wastes my time.

Specification

Never use "SHOULD" in official guidance. Do the hard work to make it simple: "MUST" when people must do it, "MAY" when there's a choice. — Caroline Jarrett

"must" when people must do it, "may" when there's a choice.

must = duty, may = power

It's not easy for everyone

Aka "It's not simple for everyone"

Don't use words like "easy", "simple", "trivial", and "not hard", because it's not.

what is "simple" or "easy" to someone might be challenging to someone else

After you do something dozens of times, it is understandable that something is “easy” to you. However, what about someone who’s never seen the UI or feature before? [...] Encourage people who are newer to the project to contribute to or address documentation that doesn’t make sense to them

— Writing Documentation When You Aren't A Technical Writer — Part Two | Stoplight API Intersection

Content

  • examples

  • tutorials

  • list of possible parameters/properties with their meaning, type and possible values

Wording

Aka sentence structure, inclusive documentation

  • make documentation explicit, not implicit: no acronyms or assuming context

  • no marketing or self-promotion: your code is not fast, efficient, reliable, convenient or secure because you say so

  • no humor: if it's 3 AM and you are debugging a problem, and you are being forced to read lame jokes to understand what some code does, you are going to get frustrated as hell.

  • avoiding alienating terms like "noobs" or even judgmental words like "simple" or "easy"

  • gendered language should also be avoided, and use second-person pronouns like "you."

  • avoid figures of speech and pop culture references, which may not be familiar to a global audience

  • when communicating on a project, use clear and accessible language for people who didn’t grow up speaking English, or read less-than-fluently.

  • avoid accidental racism by using “denylist” and “allowlist,” instead of “blacklist” and “whitelist” - or use "blocklist" and "safelist"

  • inclusive terminology

  • writing out the full name the first time an acronym is used, you can even links acronyms to their definition at the beginning or end of the document ("define things before talking about them")

Checklist

Release note

Versioning

Aka semver, semantic versioning, calver

Why CalVer

  • it signals a project is kept updated and maintained in time

  • it’s semantic for users’ eyes … as in: they instantly understand when their version was released and have an idea of the status of that project (abandoned? outdated version?)

[...] Why SemVer

  • it doesn’t mentally couple a date on a (hopefully) robust and stable release for software that might be X years or months old and still rock-solid and (maybe) bugs free

  • it clearly separates patches from changes without bounding “meaningful changes” happened in a specific month … actually it frees anyone from thinking “should we release earlier to close this month with the best up to that point and release also ASAP next month to signal these major changes?” … so it removes “unnecessary release friction”

  • one can release minor to major within the same month independently, while it would be extremely confusing otherwise to me, understanding why everything breaks between 2024.01.1 and 2024.01.2 (possibly happened the 31st of January … as one month of changes and development might mean everything!)

  • a release before Xmas and a patch after NYE really confuses me … 2023.12.2 and 2024.01.1 might mean everything and nothing at the same time … 1.7.1 on December and 1.7.2 on January would never make me even think about it … it’s a patch: I am good to update!

  • it’s the de-facto industry standard dictated by the biggest community registry that we have right now: npm

— CalVer or SemVer?. This is going to be quick: there are… | by Andrea Giammarchi | Medium

API

CLI

Error messages

Error messages as a form of documentation:

  • Humble: "An unknown error occured (-50)" -> "Sorry, we could not reach the Netflix service. Please check Network Settings to connect to an available network and use Netflix (15001)"

  • Human: "Exception has been thrown by the target of an invocation" -> "There was a problem: Your password is incorrect"; "Your AccountSid or AuthToken was incorrect. More info"

  • Helpful: "404. That's an error. The requested URL |url| was not found on this server. That's all we know" -> "That's very nice photo, but it's a bit too big. Try one that's smaller than 4000px tall by 4000px wide. Cancel - Try a different image"

  • Humor: "|illustration of beasts eating computers| We'll be back shortly. We may have forgotten to feed the wild Tumbeasts that roam our datacenter, resulting in gnawing and/or mutiny. Animal control has been alerted.", "Something went and got goofed. Retry"

— Error Messages: Being Humble, Human, and Helpful will make users Happy — Write the Docs

Apex crash - Out of memory

Apex crashed because it ran out of memory.

The most common causes of this are:

  • "Texture Streaming Budget" is too high in your video settings. Lowering this can help.

  • All other programs plus Apex combine to use too much memory. Quitting other programs can help.

  • Your Windows page file is set too small. Increasing the page file size can help. (The page file lets Windows move less important memory to disk until it's needed again.)

TECHNICAL INFORMATION:

  • Apex was using 2.3 GB of physical memory.

  • Apex was using 7.3 GB of virtual memory.

  • Apex failed to allocate 1.0 MB of memory.

  • Your PC has 32.0 GB of memory physically installed.

  • Your PC has 128.0 TB of virtual memory (with the page file).

  • After Apex exited, your PC memory load is about 84%.

Ctrl+C in this window will copy this message so you can paste it as text.

— ralph waldo cybersyn on Twitter: "this is the most helpful crash message i've ever seen https://t.co/JCy4iDPrFt" / Twitter

Just like any other form of documentation, put the relevant information first. This can be done by having the object first and the action second. The user is looking for the result, not how to get there. This is helpful when users quickly scan your error messages. "Press the back button to return to the previous page." -> "To return to the previous page, use the back button."

Errors in docs, allows you to expand on the error message without increasing it in length, while still trying to help the user understand why they are getting the error. For one error (ex: 401 status code error "Permission Denied"), there are a lot of possible causes which they clearly lay out in Error and Warning Directory.

Version message

Aka Git commit message.

Use verbes:

Personal pronoun

In my writing, I’ve almost completely switched from “you” to “we”—I find it more engaging.

Example:

  • Before: “If a property can be omitted, you put a question mark after its name.”

  • After: “If a property can be omitted, we put a question mark after its name.”

— Axel Rauschmayer on Twitter: "In my writing, I’ve almost completely switched from “you” to “we”—I find it more engaging. Example: – Before: “If a property can be omitted, you put a question mark after its name.” – After: “If a property can be omitted, we put a question mark after its name.”" / Twitter

'they' often helps avoid the 'he/she' issue in written English. — Johnny D on Twitter: "@rauschma This is good. Also 'they' often helps avoid the 'he/she' issue in written English." / Twitter

Naming

See also ../Development/Development.md

Title capitalization

Style guide

Aka stylebook

Examples:

Style guides:

See also:

PreviousDocumentationNextDrawing

Last updated