← prev | next →     Top-level ToC     /authoring-tips.html     (printable version)

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

cd my-project
mkdir doc
cd doc
touch should be your project’s overview. Explain what your project is, what it does, and why folks would want to use it. If your ../ contains substantial overview material, consider moving much of that material into The content of will render as the “front page” of your project’s docs. can for now just be a walkthrough: detailed instructions, start to finish, on how to use some basic features of your project. Be sure to use syntax highlighting for your code snippets. If you have a lot of examples, skip the file and instead create an examples directory which you can then populate with and files. should include version numbers and dates, and 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:

  • (though, for software, this is often taken care of by autogenerated API docs)