Authoring Tips

If you’re not sure where to begin, do this:

mkdir my-doc-proj
cd my-doc-proj
touch index.md _copyright
touch 010-getting-started.md 020-tutorial.md 030-examples.md 040-changes.md

Regarding those md files:

index.md

Required, but you probably already have this (maybe you named it README). Should be your project’s overview. Explain what your project is, what it does, and why folks would want to use it. The content will render as the “front page” of your project’s docs.

010-getting-started.md

How to install, set up, and get it working for the first time.

020-tutorial.md

For now can just be a walkthrough: detailed instructions, start to finish, on how to use some basic feature(s) of your project.

030-examples.md

Be sure to use syntax highlighting for your code snippets. If you have a lot of examples, skip the NNN-examples.md file and instead create an examples directory which you can then populate with NNN-this-feature.md and NNN-that-feature.md files. Likewise if you have multiple tutorials!

040-changes.md

It’s much appreciated by this reader if you’d please include dates along with version numbers. In this changes doc, summarize user-facing changes; if readers are interested in seeing individual code changes, they can always look at the version control logs.

Other ideas for documents you (or potential contributors) might write:

• cheatsheet or quick-ref
• manual (though, for a comprehensive manual, consider using multiple manual files in their own manual subdirectory)
• reference (though, for software libraries, this is may be taken care of by autogenerated API docs)
• glossary
• issues / todo
• faq