Convert README to Markdown

toolness commented 8 years ago

Currently the README is in reStructuredText, which has some disadvantages:

It's unintuitive compared to Markdown, especially for newcomers. (I haven't used it in a long time, and I'm having a difficult time making changes to it, especially given that I have no way to live-preview my changes on my local system.)
It's not possible to easily copy content to/from other Markdown content--e.g. other project READMEs, or instructions.md, or GitHub comments.

The only potential advantage I see in using RST is that it'll be easy to migrate our documentation to Sphinx, but I don't see that happening anytime soon...

catherinedevlin commented 8 years ago

I recently did a little survey of how many 18F repos had README.md vs. README.rst, and Markdown won by a million miles, so I must conclude a little sadly that Markdown in 18F's standard.

I could switch it over.

toolness commented 8 years ago

Ok! Don't get me wrong, I actually really like rst for Sphinx because it's a lot more powerful in that context... I'm just not a huge fan of it for READMEs, whose formatting needs are typically pretty simple...

Since I proposed this, I'm happy to take on this work myself, unless you really want to!

toolness commented 8 years ago

Hmm, @jmcarp noted in https://github.com/18F/autoapi/pull/75#issuecomment-231622931 that rst is better if we want our work to be reused by the wider python community.

I guess I'm fine with either, I just prefer that all our docs use the same format...

18F / autoapi

Convert README to Markdown #65