FAQ
“Why write another documentation processing program?”
See the rationale page.
“Why use Markdown? Why not LaTeX, reST, moinmoin wiki syntax, etc?”
The main goal of Rippledoc is to assist in making docs as easy as possible to create, write, and to contribute to. Aside from probably being the most widely known, Markdown is, IMO, the easiest of the markup formats to read, and also very easy to write and to remember; and pandoc-markdown tastefully adds what’s missing from original Markdown and/or CommonMark.
“But my favorite programming language uses {fave-markup}!”
Documentation often benefits greatly when others also contribute to it. Good writers may not know your markup format of choice, and may not be interested in taking the time to learn it and the its required tooling. But they very likely already know Markdown (or can learn it in 5 minutes).
“But I really do want to use {fave-markup}. Can I?”
Y’know, djot markup is quite nice too. And pandoc can use it. Shouldn’t be too much trouble to modify rippledoc to use djot (“.dj”) instead of markdown (“.md”).
“But Rippledoc is written in Python! My project uses {other-language}!”
Rippledoc is a pretty simple program which happens to be written in a few hundred lines of Python.
Regardless, under the hood, Rippledoc uses Pandoc to do the heavy lifting. Although Pandoc can translate between many different markup formats, Rippledoc is only using it to convert Markdown to HTML. There are many other Markdown implementations that you could use if you wanted to (most languages tend to have at least one implementation), though they might not have the excellent enhancements that Pandoc provides. See CommonMark for more info on Markdown and various implementations of it.
“Why use Pandoc under the hood and not {my-favorite-markdown-implementation}?”
Because Pandoc (and Pandoc’s markdown):
- supports tables, definition lists, line blocks, footnotes, and \(\LaTeX\) math
- supports code block syntax highlighting
- is high-quality and reliable
- is actively maintained
- supports the command-line options that Rippledoc requires
- runs fast
- is easy to install on GNU/Linux
“Bah, my project is hosted on GitHub (or similar); why not just let users read the docs there, since GitHub automatically renders .md files as html?”
Mainly because:
- Pandoc (used by Rippledoc) supports a number of very useful Markdown syntax extensions which GitHub’s markdown processor may not (see previous FAQ item).
- Rippledoc provides nice prev/next navigation links, a table of contents, and lets you order your docs (by numbering them in their filename).
- With Rippledoc you can customize styling (the styles.css file) and more easily incorporate your docs into your project’s website.
“Wait. Why use Rippledoc when I can just put up (or enable) a wiki?”
Because:
- You usually have to edit wiki content on the web, rather than in your text editor. Potential contributors who are skilled writers may not want to make substantial doc contributions via a web form.
- Thoughtful writers will often not want to contribute to a wiki, since their careful writing can so easily be wrecked-up by a heedless hit-and-run editor.
- Wikis require vigilant management. This includes removing spam, but also intervening when editors disagree on eachother’s changes.
- Wikis have a way of becoming disorganized while simultaneously becoming out of date, making them geometrically harder to get back on track.
- Wiki’s generally don’t support the nice syntactic markdown extensions that Pandoc (used by Rippledoc) does.
- They provide no nice table of contents, nor easy navigation links.
The authors have to provide
[[wiki links]]
manually. - If you want to move your docs at some point, it’s not always easy to extract your doc files from wikis or to migrate to another wiki.
- Changes to the wiki generally are not connected with commits to your source code repo.
“I don’t like Rippledoc’s default output style. Can I change it?”
Certainly. When you first run Rippledoc it creates a default styles.css file which you can then modify.
“I customized my styles.css, and uploaded it, but I don’t see any changes!”
Reloading the page may not be enough — you might need to clear your browser’s cache, then reload, for it to recognize the updated styles.css.