New Mercurial Website

[Steve Losh]

On Nov 2, 2009, at 10:22 AM, Adrian Buehlmann <adrian at cadifra.com>  
wrote:

> Please keep discussion on-list, so I'm cc-ing the list again
>
Ugh, I always forget to hit Reply All on my phone, sorry.

> On 02.11.2009 15:52, Steve Losh wrote:
>> On Nov 2, 2009, at 9:38 AM, Adrian Buehlmann <adrian at cadifra.com>  
>> wrote:
>>
>>> On 02.11.2009 15:01, Steve Losh wrote:
>>>> On Nov 2, 2009, at 8:36 AM, Adrian Buehlmann <adrian at cadifra.com>
>>>> wrote:
>>>>
>>>>> On 02.11.2009 14:25, Dirkjan Ochtman wrote:
>>>>>> On Mon, Nov 2, 2009 at 13:31, Adrian Buehlmann <adrian at cadifra.com 
>>>>>> >
>>>>>> wrote:
>>>>>>> There is no need to start an entirely different platform
>>>>>>> that is doomed to be byte rotten from the start because no
>>>>>>> one will update it.
>>>>>> Not having everyone update it also means coherent language,
>>>>>> structure,
>>>>>> content and more quality control.
>>>>> Oh. So you say our current wiki has incoherent language and
>>>>> structure?
>>>>>
>>>>> Where exactly?
>>>>>
>>>> Quick example off the top of my head: the Release Notes page. The
>>>> table of contents has a bunch of headings for 1.3.0 only. Are there
>>>> not subsections for the other versions? Oh, no, they're there,
>>>> they're
>>>> just not marked as headings for some reason.
>>>>
>>>> I can send a whole slew of examples later once I'm at a computer  
>>>> and
>>>> not a phone, if you like.
>>>>
>>>>> You are missing the point of what a wiki is. Or what it could be.
>>>>>
>>>>>> And content may be king, having the abundance of content that's  
>>>>>> on
>>>>>> our
>>>>>> wiki makes it hard to find the good parts and keep everything  
>>>>>> up to
>>>>>> date.
>>>>> Not at all.
>>>> Really? The API hasn't changed since 1.1? Because that's the  
>>>> version
>>>> listed on the MercurialAPI page.
>>>>
>>>> Reading the API changes page it looks like the API page *has* been
>>>> updated (it mentions ui.promptchoice) but still says "as of version
>>>> 1.1". So actually the page is not out of date but completely  
>>>> *wrong*
>>>> -- if you try to use it to code against the version of Mercurial  
>>>> it  
>>>> says it describes (1.1) you'll probably run into problems.
>>>>
>>> And you think that can be improved by starting a second site,
>>> which is not part of the wiki, so that everyone wanting to
>>> update things has to send patches?
>>
>> For the "incoherent structure" part of things: absolutely. If a small
>> group is reviewing and/or making changes there's less of a chance  
>> that
>> subheadings will be added for some sections and not for others (for
>> example). The site will feel more cohesive which is a good thing to
>> present to first-time users.
>>
>> Git and Bazaar both have good-looking frontend sites with separate
>> wikis, so the concept is certainly not something new and can
>> definitely work.
>>
>> For the out-of-date part, I'm not sure. I think the smaller size of
>> the frontend site, and the fact that there are actually people
>> responsible for it (as opposed to the wiki where it's easier to say
>> "eh, someone else can update this") will help in that respect.
>>
>
> So you want to have the page MercurialAPI in a static page instead
> of in the wiki?
>
> I don't think that's exactly a good idea.
>
I don't think it is either. Some pages, especially complicated ones  
like this, are probably better left on the wiki. I'm just pointing out  
one example of the staleness and incoherence that results from lots of  
people working on a wiki over a long time.

What I do want is for first time users of Mercurial to see a landing  
site that's concise and coherent. Once they're a little more  
comfortable with Mercurial (which they certainly are if they're  
looking at its internal API) it's fine for them to go to the wiki.

> In any case, I'm surprised about what people think about the wiki.
>
> It seems like updating the wiki is no longer appreciated. If that's
> the case, then I certainly won't waste my time there any more if the
> wiki is in such a lousy state that the project needs to instate
> another crew that ignores patches.
>
The wiki is great for experienced users that know what they're looking  
for. I use it all the time and definitely appreciate it.

It's not so great for brand new users who hear about Mercurial from a  
friend or blog post and decide to check it out.

I'm not sure what you mean about another crew to ignore patches.  Does  
the current core Mercurial crew ignore patches? It doesn't seem like  
that to me, but then again I haven't submitted many. David has also  
seemed pretty good about accepting patches when I worked with him on  
this.

> And I certainly won't start to send patches for html pages that
> are reviewed by a single person simply to learn that they are
> rejected after 48 hours. No thanks.
>
Actually at some point I could have sworn David and I talked about  
using Markdown or Restructured text or something for the content...  
That doesn't seem to have happened. I wouldn't like editing raw HTML  
for something like this either, so we should definitely look into  
using a sane, clean markup language for all the body copy.

> It's funny that much bigger projects manage to have their front
> pages as a wiki page. Have a look at Wikipedia.
>
Wikipedia is kind of a special case because that's the entire