Authoring Tips

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

cd my-project
touch README.md
mkdir doc
cd doc
touch getting-started.md tutorial.md examples.md changes.md

Regarding those md files:

../README.md

Required, but you probably already have this. 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. If you prefer, you can have ../README.md be minimal, and instead put the bulk of the overview material into a doc/index.md file.

getting-started.md

How to install, set up, and get a hello-world example working.

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.

examples.md

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

changes.md

It’s much appreciated by this reader if you’d please include dates along with the version numbers. In this 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.md
• quick-ref.md
• manual.md (though, for a comprehensive manual, consider using multiple manual files in their own doc/manual subdirectory)
• reference.md (though, for software libraries, this is may be taken care of by autogenerated API docs)