Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

Converted README to Markdown #1007

Closed
wants to merge 3 commits into
from

Conversation

Projects
None yet
4 participants

I've converted the README to Markdown.

Owner

brixen commented Jun 12, 2011

Yes, 'most recent' is correct.

Could you explain why you think this is a good change?

I have rejected converting the README to Markdown before for these reasons:

  1. The rendering of the Markdown on Github actually makes this much harder to read. The headings are huge but the text is rendered very small and trails across the page making it much more difficult to read.
  2. Even if the rendering on Github were superb, READMEs are text files that should give core information for someone browsing the source code. This change makes the text even harder to read with '## Foo ##' a lot uglier than a simple '1. Foo'
  3. Github already renders links clickable in plain text files and we have much more extensive docs available on http://rubini.us and already in the repository that someone can access with a simple 'rake docs' command.
  4. The README needs to be cleaned up and about 30% of the information removed. The remaining content is very easy to read in plain text format.

I am very much opposed to changing the format of the README.

meh commented Jun 12, 2011

I think markdown reads better when used properly, for example using

Title
=====

Subtitle
--------

Instead of # Stuff #

Owner

brixen commented Jun 12, 2011

@meh

We don't need any subtitles in the README. The use of heavy === underlining the few headings is unnecessary in text. We use Markdown in the docs because it's 500% better than trying to write docs embedded in HTML but it adds only complexity to a simple text file.

@brixen

Thanks for your feedback. I've converted README to Markdown because of the superb (IMHO) visualization that @github provides. Almost every great project in Github includes a great README in Markdown, so I thought it should be a nice idea to Rubinius to have one.

An alternative: we may also provide a plain text version of the README (I don't know if Github will choose the Markdown version instead of the plain text version to show when someone opens, I have to check). It is not "DRY" but it provides a nice visualization on Github without removing the plain text README.

About the Recent x Updated: we currently have "Most current documentation". I agree that recent can be better than updated, but I don't like "most current".

Owner

brixen commented Jun 12, 2011

@rodrigoflores

Thanks for the additional explanation. The part of the README with RVM information needs to be reworked. We don't need to duplicate the RVM information. One step to install the current version and a link to RVM should be all that is included. Then the text could be something like "See the RVM documentation."

I'm really curious why you think Github renders the Markdown better than plain text. I could skitch the two side-by-side and show how the Markdown rendering straggles across the screen with short and long text lines interspersed providing a very poor reading experience. The Github rendering is just terrible for readability.

Owner

brixen commented Jun 13, 2011

This is a rendering of the Markdown format:
https://skitch.com/brixen/frk4k/rodrigoflores-rubinius-github

This is a rendering of the plain text. As the notes point out, there is nothing the Markdown format gives other than a needless horizontal rule and big heading text.
https://skitch.com/brixen/frk4p/rubinius-rubinius-github

@brixen

Another doubt: Can we at least change most current to "most updated" or "most recent" ?

@ghost ghost assigned brixen Jun 22, 2011

Owner

brixen commented Jul 12, 2011

I've simplified the README quit a bit. There are lots of places that the built-in documentation could be improved for folks getting started with Rubinius. I'd like to focus efforts there.

@brixen brixen closed this Jul 12, 2011

Owner

jc00ke commented Feb 1, 2015

7f71916 😉

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment