handmade.network » Wiki » Wiki/Editorial Guide

Wiki Content

We are currently in new territory with the wiki.

There could be various splits in how content is written. A portion could be in the form of how-to guides or tutorials. Another portion could be more of an article as an organized breakdown that digs deep into the internals of a certain topic, or anything suggested here, and so on. So the wiki may not end up being a traditional wiki. We won't establish official rules and guidelines yet—in order to explore what handmade folks want to say.

Hence you are free to explore how to present a topic you wish to discuss.

Writing style

Titles

Use the following categories at the start of your titles to aid in organization until more advanced categorization features are developed:

  • Wiki/ - articles related to the wiki itself, how to write and edit, etc
  • Tutorial/ - articles written in a tutorial format, with step by step instructions

If your entry isn't strictly a meta-article nor a tutorial, there is currently no requirement to prefix your title.

Markdown conventions

Headings

Articles have a title outside of the article text itself, so don't use a first-level heading for the article title in the body text. Instead, use first-level headings for the highest-level outline of your content, for example:

1
2
3
4
5
# Overview
# Getting Started
# Potential Issues
# Resources
# Conclusion

Use second- and third- level headings to provide finer grained outlines for individual sections:

1
2
3
4
5
6
7
# Getting Started
## Setting up your environment
### Windows
### Linux
## Your first file
## Dealing with errors
### Specific compiler errors

Asides

Handmade Network's flavor of markdown allows you to write expandable asides in your text:

An aside is written like a quote, but the first line begins with ^, like so:

1
2
> ^ Aside title
> Aside **body**
Asides can also be nested as deeply as you want, but be considerate of your readers.

Code fences vs Code blocks

Code fences allow you to specify a language after the start of the code fence. Specifying a language will run the syntax highlighter and show line numbers next to the code block.

```python
def foo(x):
    pass
```

becomes

1
2
def foo(x):
    pass

If you just want to have preformatted text that shows up in a monospace font, you can either omit a language next to the start of the code block, or simply indent the lines by at least four spaces:

    bit 15       8      0
         0000101000101010

becomes

bit 15       8      0
     0000101000101010