Rationale and Benefits

John Gabriele

It’s often 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
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 the docs 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

Rippledoc aims to fix that situation:

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 are numbered and have titles (their “% First Line”), there’s zero extra work required. 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 got something workable that can start to grow.
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.
It’s easy for potential contributors to install the rippledoc script, so that they can preview their more substantial contributions. Or they could even wing it, since Markdown is quite easy to get right on the first try.
When your docs are more bite-sized, aptly-named text files, it lowers the procrastination barrier. Start small. Write a small index.md file, and maybe an 040-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 (note, must be named like NNN-foo.md).
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.
Finally, using a script like Rippledoc now doesn’t tie you to continued use of it in the future. 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.