Status quo of Mercurial wiki

[Adrian Buehlmann]

Since so many people seem to be disappointed about the
wiki, I would like to know:

Why do those people not edit the wiki to improve it instead of
just complaining about how bad the wiki is?

What's the problem with editing the wiki?

Is it really that hard to edit the wiki?


_______________________________________________
Mercurial mailing list
Mercurial@...
http://selenic.com/mailman/listinfo/mercurial

[Dirkjan Ochtman]

On Mon, Nov 2, 2009 at 16:01, Adrian Buehlmann <adrian@...> wrote:
> Why do those people not edit the wiki to improve it instead of
> just complaining about how bad the wiki is?

Editing the wiki is a lot of work, for example, I tried at one point
to merge some of the places that talk about setting up hgwebdir, but
it's not all that easy to decide what content to keep, what to
discard, what to merge, what the best outline would be, how to lay out
everything, etc, etc. On top of that wiki markup isn't always all that
straightforward.

(Nowadays I don't spend a lot of time reading the wiki, mostly I just
point people at it.)

> Is it really that hard to edit the wiki?

To make it coherent and good, yes, that's hard work. Minor corrections
aren't that hard, but there's still a certain barrier to entry.

And then there's the fact that sometime you'll have to research what
the problem or the solution is (e.g. what API is in 1.1).

Cheers,

Dirkjan
_______________________________________________
Mercurial mailing list
Mercurial@...
http://selenic.com/mailman/listinfo/mercurial

[rpelisse]

2009/11/2 Adrian Buehlmann <adrian@...>

Since so many people seem to be disappointed about the
wiki, I would like to know:

Why do those people not edit the wiki to improve it instead of
just complaining about how bad the wiki is?

I didn't see anybody complaining about the wiki. I read you complaining about not using the wiki as a frond end :)  

What's the problem with editing the wiki?

I don't think there is. 

Is it really that hard to edit the wiki?

Idem. 

The thing is that it is a wiki, wiki is not a new word to describe how to make a website. Wiki describes a certain kind of web application, but I don't think a wiki is the best way to publish everything on (and clearly the people behind this new website kind of feel the same)... 

--
Romain PELISSE,
"The trouble with having an open mind, of course, is that people will insist on coming along and trying to put things in it" -- Terry Pratchett
http://belaran.eu/

_______________________________________________
Mercurial mailing list
Mercurial@...
http://selenic.com/mailman/listinfo/mercurial

[Alexander Schatten-2]

First I would like to say, that I believe also, that the new website is a big improvement; it makes a much better impression. Particularly the "guide" is excellent. Also the Quickstart text is very snappy.

As I started with Mercurial, I found the information in the wiki ok, but rather confusing, partly redundant and not very well structured. A hodgepodge as most wikis tend to develop to over time. Most things could be found, but I believe the new guide is a big improvement for beginners.

Now to answer your question; there might be a surprisingly simple answer. Why would I as *beginner* or not-Mercurial expert want to edit a Wiki that I find confusing? I have not the skills to do so. You have to have a proper understanding of the information available to add new pages or change them. Plus: I do not want to fiddle around with the wiki, I want to get some proper initial information on the project (as is provided now). Later on, I might contribute to a Wiki as well.

In my opinion, a Wiki is not the right solution for a project website at all. Unless it is used poor-mans CMS for the development team. A wiki can *support* the documentation on a website (e.g. for a FAQ section), but the main part should be written by experts from the project or technical writers associated to the project.

Design and first impression also make a difference, of course.

So I would say, from my point of view, a very good decision. Just one minor comment: The header-fonts e.g. in the guide look pretty bad, at least in my setup (OS X, Firefox). They are not sharp and look like bitmaps with low resolution and do not fit to the rest of the text. Why not use default fonts?


Alex

-------- Original-Nachricht --------
> Datum: Mon, 02 Nov 2009 16:01:17 +0100
> Von: Adrian Buehlmann <adrian@...>
> An: Mercurial@...
> Betreff: Status quo of Mercurial wiki

> Since so many people seem to be disappointed about the
> wiki, I would like to know:
>
> Why do those people not edit the wiki to improve it instead of
> just complaining about how bad the wiki is?
>
> What's the problem with editing the wiki?
>
> Is it really that hard to edit the wiki?
>
>
> _______________________________________________
> Mercurial mailing list
> Mercurial@...
> http://selenic.com/mailman/listinfo/mercurial

_______________________________________________
Mercurial mailing list
Mercurial@...
http://selenic.com/mailman/listinfo/mercurial

[Giorgos Keramidas]

On Mon, 02 Nov 2009 16:20:22 +0100, "Alexander Schatten" <ml_alexanderschatten@...> wrote:
> So I would say, from my point of view, a very good decision. Just one
> minor comment: The header-fonts e.g. in the guide look pretty bad, at
> least in my setup (OS X, Firefox). They are not sharp and look like
> bitmaps with low resolution and do not fit to the rest of the
> text. Why not use default fonts?

This is a stylesheet issue.  They look crafty here too (Firefox 3.5
running under X11 on FreeBSD), but only if my Firefox preferences are
set to "Allow pages to select their own fonts":

  http://people.freebsd.org/~keramida/hgweb.png

The CSS style of the website uses a .font-family value of:

    Optimer,Helvetica,Arial,sans-serif

'Optimer' is not available here, and 'Helvetica' is a bitmap font.  So
the display of characters looks edgy at large font sizes.

I'm not a web designer myself, but things may look better with a font
family that is more likely to be a vector font on UNIX too, i.e.:

    Optimer,DejaVuSans,Helvetica,Arial,sans-serif

or just 'sans-serif'.

_______________________________________________
Mercurial mailing list
Mercurial@...
http://selenic.com/mailman/listinfo/mercurial

[Eric Larson-5]

At Mon, 02 Nov 2009 16:01:17 +0100,
Adrian Buehlmann wrote:
>
> Since so many people seem to be disappointed about the
> wiki, I would like to know:
>
> Why do those people not edit the wiki to improve it instead of
> just complaining about how bad the wiki is?
>

When I first started using the wiki, it could be difficult to feel confident in the content. It was a default moinmoin template and some of the content could be inconsistent. Even when it wasn't actually inconsistent, as a new user, it was easy to feel as though it wasn't consistent. This is a very subjective opinion, but I think it is a valid usability concern with any wiki. A resource that anyone can edit means there is a potential chance that the page your looking at could be anything from a scratch page you found by mistake, a new proposal, or any number of non-working concepts that are most likey not intended for a user looking for documentation.

With that in mind, simply editing the wiki doesn't help anything because there is still the question of what the canonical answer to a question is. Even when an answer is "it depends", knowing that you really have a choice and the software was designed to give you that choice allows a user to feel empowered as opposed to feeling like you might be setting yourself up to fail. I think wikis generally don't help users consider the content to be authoritative, which doesn't help navigate the new wealth of new options available when choosing a DVCS such as Mercurial.

> What's the problem with editing the wiki?
>
> Is it really that hard to edit the wiki?
>

I can't say I've ever edited the Mercurial wiki, but that is primarily because I'm just a simple user. When I first started using Mercurial, the wiki was a valuable tool, but more often then not I would trust the red book to guide my way. This was because I knew the content was meant to be authoritative. While I can appreciate the wiki as both a CMS and a technique to keep documentation up to date, the new website provides more authoritative sources to help new users feel confident understanding the software as it was intended. I'm sure it would have been possible to do this with the wiki, but that wasn't what was decided.

Personally, I think they did a great job and based on the recent comments regarding using the wiki, a better tactic would simply to be patient and continue to improve the wiki content. Both the wiki and the website are simply tools that speak to different audiences and should be appreciated/evaluated as such.

Just my two cents.

Eric Larson

>
> _______________________________________________
> Mercurial mailing list
> Mercurial@...
> http://selenic.com/mailman/listinfo/mercurial
_______________________________________________
Mercurial mailing list
Mercurial@...
http://selenic.com/mailman/listinfo/mercurial

[Adrian Buehlmann]

On 02.11.2009 16:20, Alexander Schatten wrote:

> First I would like to say, that I believe also, that the new website is a big improvement; it makes a much better impression. Particularly the "guide" is excellent. Also the Quickstart text is very snappy.
>
> As I started with Mercurial, I found the information in the wiki ok, but rather confusing, partly redundant and not very well structured. A hodgepodge as most wikis tend to develop to over time. Most things could be found, but I believe the new guide is a big improvement for beginners.
>
> Now to answer your question; there might be a surprisingly simple answer. Why would I as *beginner* or not-Mercurial expert want to edit a Wiki that I find confusing? I have not the skills to do so. You have to have a proper understanding of the information available to add new pages or change them. Plus: I do not want to fiddle around with the wiki, I want to get some proper initial information on the project (as is provided now). Later on, I might contribute to a Wiki as well.
>
> In my opinion, a Wiki is not the right solution for a project website at all. Unless it is used poor-mans CMS for the development team. A wiki can *support* the documentation on a website (e.g. for a FAQ section), but the main part should be written by experts from the project or technical writers associated to the project.
>
> Design and first impression also make a difference, of course.
>
> So I would say, from my point of view, a very good decision. Just one minor comment: The header-fonts e.g. in the guide look pretty bad, at least in my setup (OS X, Firefox). They are not sharp and look like bitmaps with low resolution and do not fit to the rest of the text. Why not use default fonts?
>
>

Quite interesting to know that the wiki is broken that much.

It was not my impression I had and thus I tried to update it
as much as I could. It was also nice to see lot's of people
fixing things while they were reading. And the spam was
surprisingly low. I kept reverting spam in the past.

I also don't understand why it was impossible to add
the guide to the wiki.

But obviously, people seem to now prefer editing
static pages by sending patches.

I don't.

In any case, I should probably stop wasting my time
on that horrible wiki then.
_______________________________________________
Mercurial mailing list
Mercurial@...
http://selenic.com/mailman/listinfo/mercurial

[Alexander Schatten-2]

> Quite interesting to know that the wiki is broken that much.

It was not my intention to offend you; and this is also not what I said; I did not say that it was broken; I said, that there was a lot of information but not very accessible, duplicated information,... In my opinion it was not very well organised. That is not to say, that the provided information was bad as such.

I think, that you did an important work in the past, and I do not understand why it should not be possible to see the strenghts in both systems:

The new website has in my opinion a MUCH better appearance then the old one. Particularly for beginners and people who do not know Mercurial. The previous one was more hackers-paradise (from the appearance) but not very attractive to newbies, I believe.

> In any case, I should probably stop wasting my time
> on that horrible wiki then.

I see no reason for exaggeration.

So why not leave the new design and website for general information, downloads, the guide; and add the "old" wiki for more specialised information, stripped from documents for starters.


Alex
_______________________________________________
Mercurial mailing list
Mercurial@...
http://selenic.com/mailman/listinfo/mercurial

[Andrew Lentvorski]

Adrian Buehlmann wrote:

> In any case, I should probably stop wasting my time
> on that horrible wiki then.

Nobody is saying *you, personally* are doing a poor job or that it is
unwanted.

However, documentation is a large job.  It takes more than one person to
do it without burning out, and the main developers have to decide that
it is worth some of their time to "weed the garden" as well since
they're some of the only people who understand how everything goes
together in the big picture sense or some of the deeper technical issues.

A "Landing Page" is a nice thing, but it doesn't solve the underlying
problem that the Wiki/Documentation needs regular attention from
important people.  And, if the landing page starts expanding too much in
scope, it will start taking the time of people away from improving the
Wiki/Documentation.

Documentation always gets short shrift in open source projects (I'm as
guilty as anybody).  This is nothing new.

-a
_______________________________________________
Mercurial mailing list
Mercurial@...
http://selenic.com/mailman/listinfo/mercurial