Rippledoc

Rationale and Benefits

John Gabriele

It can be difficult to find good documentation. Some reasons for this include:

  • the developer is busy with other things and hasn’t yet made time to create or improve the docs
  • the developer doesn’t like or isn’t familiar with the available doc formats and/or tools
  • users were not helping improve the docs and the developer lost interest in doing it all him/herself
  • the developer isn’t very good at writing docs, and ends up avoiding writing them
  • some good docs were written once, but no one pitched in and they got out of date
  • writing a full manual is a daunting task and takes a lot of motivation to get started
  • the developer doesn’t want to get tied down to any one particular language-, project-, or technology-specific doc format or toolset
  • the developer simply doesn’t like writing docs, and the job keeps getting pushed to the bottom of the todo list

But without good docs you won’t have many happy users; and without them, projects tend to flounder.

Rippledoc aims to remedy the situation. Here’s how:

  1. It’s particularly easy to use. You just create a doc directory, write some docs as simple text files, then run the script. Except for creating a "_copyright" file and making sure the docs have titles, there’s zero extra work required (you can optionally change the order your docs appear in the autogenerated toc.conf file). You don’t have to spend your time reading a manual or learning how to configure anything — just run the script, upload your docs to the web, and you’ve something workable that can start to grow.

  2. Your docs are formatted in Markdown (specifically Pandoc-flavored Markdown). Pretty much everyone already knows Markdown (it’s used on Reddit, Stackoverflow, GitLab, GitHub, Discourse forums, in blogs and in their commenting systems, and for most README’s). Potential contributors will not have to learn any new markup formats or complicated tools to contribute to your docs; they can just edit the text file and submit the pull-request — a minimal barrier to entry for potential contributors.

    Another benefit of using Markdown in particular is that it looks excellent as plain text in your editor. Very easy to read, easy to write, and easy syntax to remember. See the quick markdown example.

  3. It’s very easy for potential contributors to install Rippledoc so that they can preview their more substantial contributions. Failing that, they could even preview their changes by copying/pasting into an online Pandoc Markdown processor. Or they could even wing it, since Markdown is quite easy to get right on the first try.

  4. With Rippledoc, your docs are typically bite-sized aptly-named text files. This helps lower the procrastination barrier; you (and potential contributors) can start small. Write a small ../README.md and maybe an examples.md file, run Rippledoc, and immediately get some results that you can make available. If unsure of where to start, see authoring tips.

    This also, again, lowers the barrier for potential contributors. A collaborator can send you a single text file which could simply be dropped into your docs directory to automatically become a new article in your docs.

  5. Since they’re just static html (and md) files, to make the docs available online, you rsync/ftp/scp/upload your whole docs directory to your webserver or wherever the docs are hosted. Some module repositories, like Python’s Cheeseshop, will host plain html files like this for you.

  6. Finally, using Rippledoc now doesn’t tie you to continued use of Rippledoc in the future; it’s just a simple program that processes markdown files and stitches the output html together. If you decide you don’t like Rippledoc after all, just delete the generated files and you’re back to your plain directory of text files.