How to Write Documentation

Wiki

Overview

This document outlines practices for presenting a consistent documentation style. The information contained is meant to serve as a guideline to help improve documentation efforts on the wiki.

Managing the wiki

First, you need to have permissions to edit the wiki. Fortunately these are quite easy to get – just ask in #documentation in our Slack workspace and someone will get you set up.

Creating an article

Once you’ve got Editor permissions (see above), all sorts of fancy new buttons will show up for you:

These should allow you to edit any existing article, edit existing categories, add new articles within a category, etc. To add a new article (or edit an existing article), the interface looks like this:

If you have any questions on the specifics of how to manage and publish the wiki content, please ask in our #documentation channel.

Categories

Adding new categories should be infrequent. The current categories are designed to be a small group of buckets to help organize articles.

denhac

Articles found under the denhac category are related to denhac policies, procedures, and additional information on how the space can be used.

Areas

Articles found under the Areas category are related to specific activities as outlined in the article. These areas occasionally move around the building, so keeping the area names free of location information can help keep the wiki accurate.

Equipment

Member accessible equipment and tools belong in this category.

Tech Docs

Technical documents related to the space’s infrastructure, such as networking, belong in this category.

How To

“How To” articles are written by members for the purpose of sharing knowledge with other members.

Tags

Tags should be used to tie together articles that are associated. Keeping tags limited and reusing tags when possible make searching easier for members.

Articles

Titles

Capitalize the first letter of every word in the title, but do not capitalize pronouns, articles, prepositions, and conjunctions. A good rule of thumb is to not capitalize words that are two letters.

Formatting

Make use of headings to take advantage of the automatically generated “Table of Contents” that will appear in the right column. Headings should follow guidelines for accessibility.

Linking Resources

When linking to other pages in the wiki, use a hyperlink that does not open new tab.

When linking to resources outside the wiki, use a hyperlink with “open in new tab” selected.

Article Types

Currently identified article types are “Area” and “Equipment”. These types should follow a consistent format as other articles of the same type.

Table of Contents