[PATCH 0/6] Documentation, reStructuredText and readthedocs.org

[Finucane, Stephen]

On 02 Oct 18:41, Finucane, Stephen wrote:
> > On Wed, Sep 30, 2015 at 07:01:37PM +0100, Finucane, Stephen wrote:
> > > Could you kindly elaborate a little further on why you though it
> > > necessary to transition to reStructuredText? We're not making use of
> > > any of the fancy features of rest but it's still adds a lot of cruft
> > > (a Makefile? In a Python project? Surely not! :D).
> > 
> > I wish you wouldn't use any kind of dogma to judge work. Why would one
> > not use make and makefiles when it's handy to do so?
> [...] 
> > Overall, I don't think markdown offers enough documentation authoring
> > tools for project-wide documentation. There are other alternatives that
> > would work as well (asciidoc comes to mind), but given that it's a
> > python project, I went for sphinx and reStructuredText.
> 
> No no, we're not trying to compare Markdown vs. rST here: as you've correctly
> pointed out they are different tools with different use cases. My question,
> which I don't think has been answered yet, is why do you think it necessary
> to transition to reStructuredText for this particular project? Are you
> planning to flesh out the documentation in such a way that we need features
> like TOC or images and figures? Do we plan on generating PDFs or other
> documents? Do we plan to include native markdown in our documents? If so,
> that's fantastic - just tell us as much. If not, you'd have to question the
> value of doing stuff for just because we can. I'm not in any way saying this
> is a bad idea so don't take it personally: I just want to understand your
> position on the matter so I can help you.
> 
> Keep up the good work!
> Stephen
> 
> PS: If possible, could you include information like this (a.k.a. your
> rationale) in cover letters to help explain why you're adding a given
> features (cover letters, like commit messages, should focus on "the why"
> rather than "the what"). Reviewers don't necessarily have the "big picture"
> understanding of an issue that you might possess so it's super helpful!
> 
> PPS: I think you'd like this article on Markdown and some of the issues
> with it. Typical Ars excellence: 
> 
>   http://arstechnica.com/information-technology/2014/10/markdown-throwdown-what-happens-when-foss-software-gets-corporate-backing/1/.

I've merged the typo fixes, but I'm going to hold off on the rST until there's
a reason to switch. I like Markdown: it's easy to understand, it works well
with GitHub, and the docs available on ReadTheDocs shows it works well there
too. Unless we add an extensive amount of additional documentation (which I'd
love to see!), this seems unnecessary. However, don't let this undermine the
effort: right idea just the wrong time, IMO.

Stephen