How to Make How To Pages

In this doc, you'll learn: how to structure a clear how-to similar to the other pages in this wiki. A 'what you'll learn' item like this one should come at the top, and be a very concise summary of the one or at most two things you'll learn in this page. If you've got more things to tell people, make more pages; when articles get too long, they're too hard to absorb.

Before You Begin

• List anything your audience should have prepared or otherwise figured out before they dive in. For example, a manufacturing or packaging page might list tools and components needed. Also try to include links (possibly to other pages in this wiki hint hint) on what to do if you don't have one of these prerequisites satisfied.

Quickstart

• Your first section should be a bullet list 'Quickstart' section.
• The quickstart should walk people through the steps of completing the most wrote, basic version of the task, or give a broad overview of the process; special cases, editorial comments or other items that aren't absolutely mandatory for basic success don't belong in the quickstart.

Detail Sections

• After the quickstart, include as many sections as necessary to describe each step in more depth.
• These sections are appropriate for optional steps, alternative (but still similar) approaches, and other details that don't fit the quickstart.
• Still keep these sections concise: mostly pictures or videos, and bulleted lists.

Linking Resources

• Pictures and videos are worth a zillion words; use them.
• Provide copies of useful docs, like laser cutting patterns, instruction sheets, and any other docs you used in your process.
• Pictures and other docs should go in a directory in the repo named similarly to your article name.
• Videos are too big to upload to the repo; share them on a video sharing service and link to them.

FAQ [optional]

• If you get a lot of questions or problems with your article, you may consider making an FAQ at the bottom. This is a judgement call: answers to core questions should probably go in the body text, but in order to avoid bloating the text, more tangential questions might more sense to answer in the FAQ, which can just link out to interesting discussions in the issue tracker if you like.