Rationale and Benefits
It can be difficult to find good documentation. Some reasons for this might 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 docs were written once, but they got out of date
- writing a full manual is a large task and takes a lot of motivation to get started
- the developer is hesitant to invest time into and possibly 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 you tend to lose motivation to work on your software. It becomes a vicious cycle.
Rippledoc aims to remedy the situation.
Here’s how Rippledoc can help create good docs for your project:
It’s particularly easy to use. You just create a
docsdirectory, write some docs as simple text files, then run the script. There’s zero configuration (unless you’d like to change the order your docs appear in the autogenerated table of contents). 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’re done.
Your docs are formatted in Markdown (with some Pandoc enhancements). Pretty much everyone already knows Markdown (it’s used on Reddit, Stackoverflow, Github, in many README’s and blogs, etc.). Potential contributors will not have to learn any new markup formats or complicated tools to contribute to your docs.
Another benefit of using Markdown is that it looks great as plain text in your editor. Easy to write, easy to read, easy syntax to remember. See the quick markdown example.
With Rippledoc, you modularize your docs into bite-sized files. This helps lower the procrastination barrier; you (and potential contributors) can start small. Write a small index.md and maybe an examples.md file, run rippledoc.sh, and immediately get some results that you can make available. If unsure of where to start, see authoring tips.
This also greatly 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 1 become a new article in your docs.
All of your doc pages have their source readily available via a link in its footer (try it on this page), giving potential collaborators another way to quickly access doc source and/or send you changes.
Making the docs available online is easy. Just rsync/ftp/scp your whole docs directory to your webserver. Some module repositories, like Python’s Cheeseshop, will host plain html files like this for you.
Finally, using Rippledoc now doesn’t tie you to continued use of Rippledoc in the future; it’s just a simple program that processes and stitches together markdown files. If you decide you don’t like it, just delete the generated files and you’re back to your plain directory of text files.
Well, almost automatically; you’d also need to add the file to your toc.conf.↩