Marketing reST (was Re: What YAML engine do you use?)

[richard]

Aahz wrote:
> While I can see how you'd get that impression of reST, it's not true:
> like Python, reST is intended to be simpl*er* and readable, but not
> simple.  The joy of reST is that I can concentrate on writing instead of
> formatting, just as I do when writing Usenet posts.  ;-)  Even after
> using reST for a long time, I'm still constantly looking up features that
> I use rarely (such as correct formatting of URLs).
> But reST is great because it's relatively unobtrusive.  Those of us
> who've used reST to document code for a long time have gotten into the
> habit of using some reST-isms even when not writing reST: have you
> noticed the number of Pythonistas who use constructs like ``foo()``?
> Even if you didn't know it was from reST, the meaning is obvious.

And this is the core of it for me too (if you want simple, use Word).
Roundup's documentation__ (in particular the `Customisation Doc`__ which is
now huge) is entirely written in reST. It uses a fraction of the total pool
of reST constructs, but I believe the end result is perfectly legible. I
also tend to write in reST style when composing emails (a biggie for me is
starting examples with "::").

Anyway, some sample Roundup docs:

__ http://roundup.sourceforge.net/doc-0.8/index.html
__ http://roundup.sourceforge.net/doc-0.8/customizing.html


> As you say, reST can/does get messy when you're doing complicated things,
> but it stays more readable than XML/DocBook.

Indeed - I chose to use reST for Roundup's documentation for two very
important reasons:

1. lower the barrier for me to write the docs - and I am *really* happy with
how current the Roundup docs stay, because I don't feel like actually
writing them is a pain, as opposed to any sort of Markup Language format,
and
2. the first contributor of docs suggested it, and I've had several
contributors since. It's easier for contributors to write for Roundup's
documentation - even if they don't get the reST markup correct, it's
trivial to fix. This is less the case with a Markup Language.


    Richard