Skip to content
This repository has been archived by the owner on Sep 14, 2019. It is now read-only.

Convert README to Markdown #65

Open
toolness opened this issue Jun 29, 2016 · 3 comments
Open

Convert README to Markdown #65

toolness opened this issue Jun 29, 2016 · 3 comments

Comments

@toolness
Copy link
Contributor

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
Copy link
Contributor

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
Copy link
Contributor Author

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
Copy link
Contributor Author

toolness commented Aug 5, 2016

Hmm, @jmcarp noted in #75 (comment) 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...

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants