Rippledoc
← 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 index.md tutorial.md examples.md changes.md

index.md should be your project’s overview. Explain what your project is, what it does, and why folks would want to use it. If your ../README.md contains substantial overview material, consider moving much of that material into index.md. The content of index.md will render as the “front page” of your project’s docs.

tutorial.md can for now just be a walkthrough: detailed instructions, start to finish, on how to use some basic features 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.

changes.md 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:

  • cheatsheet.md
  • quick-ref.md
  • manual.md
  • reference.md (though, for software, this is often taken care of by autogenerated API docs)