Re: [PATCH 1/5] README: use markdown syntax

From: Jeff King <peff@peff.net>
Date: Feb 24, 2016, 10:18 UTC
Message-ID: <20160224101857.GB20807@sigill.intra.peff.net>
In-Reply-To: <alpine.DEB.2.20.1602240801550.3152@virtualbox>

On Wed, Feb 24, 2016 at 08:08:52AM +0100, Johannes Schindelin wrote:

Show 15 quoted lines

> > Markdown when rendered may be easier to read, but plain text is even
> > easier, and it somehow feels backward to cater to those who browse
> > at GitHub sacrificing those who use "less" in the source tree.
> 
> That assumes that the primary audience of the README file is the
> developers who already decided to clone the repository, as opposed to
> people browsing the README file in the browser to determine whether they
> found the correct project, or to read up on the background of the project
> without downloading the entire source code.
> 
> I'd wager real money (without scientific evidence. just going on common
> sense) that your 'less' people are in the vast minority.
> 
> Since I am convinced that markdown'ed READMEs enhance the user experience
> dramatically, Git for Windows has one already for a long time.

Yeah, I agree. I cannot imagine why I would read Git's README at this point in time. And I find I primarily consume READMEs on the web these days, as they are the first step in me figuring out whether a project is worth looking into.

Whereas I _do_ care what things like Documentation/technical look like, or CodingGuidelines, because I actually refer to them locally.

IMHO the title formatting is somewhat moot, though, as we can have our cake and eat it, too, with the "====" underlines. I don't think they are any worse than the lines of slashes in the original. :)

I'd worry more about the [] links from patch 2, but even those are fine by me.

-Peff