Style Guide

Headings

I try to write headings in one of two forms:

• "Doing the thing": an action using a gerund (verb+ing) form can describe how a user can do something while being friendlier than the imperative form ("Do the thing!").
• "Fancy stuff": a noun phrase can be used when describing a particular part or feature of the project or documentation.

Length

The most important part of a heading is that it conveys the contents of the section below it. After that, try to keep headings short and concise.

Capitalization

Capitalize headings like movie titles. Each word is capitalized, with the exception of words like a, an, the, but, as, if, and, or, or prepositions.

Searchability

In the future, I plan to add search functionality to docgen. So it's good practise to keep searchability in mind when coming up with heading titles. This can improve the user's experience. Keep in mind both what terms the user may search for, and that is conveys its contents when shown in a search result. It may be possible that a search only matches the body text, but that the heading is the first part the user sees.

Inline Code

Avoid punctuation immediately after a long inline code block ("For example: the inline code block you are reading now is an extremely long inline code block that is hopefully longer than the content width of the page."). Inline code is styled to have no line breaks for readability. However, this can cause the punctuation after the code block to be moved to the next line, causing orphaned punctuation from the rest of the sentence as shown above.