1. David Soria Parra
  2. hg-website

Wiki

Clone wiki

hg-website / InformationFlow

Discussion about the information flow for the Mercurial Website.

First step: The needs of visitors

First time visitors

Imagine I'm a first time visitor of the website. How did I hear of Mercurial?

  • "I read an article or a blog post about it"
  • "I read a 'which VCS' discussion"
  • "I just read the word in a chat"
  • "A friend told me about Mercurial"

The last two users will want a basic overview 'what Mercurial is', before they download. All will want a basic description how to use Mercurial - maybe after they downloaded it.

Windows and MacOSX Users will want a Download-Link, as well as GNU/Linux users whose distribution doesn't offer the most recent Mercurial version.

Windows Users should directly see a link to TortoiseHG.

<ArneBab> I just had a look at the http://git-scm.com site. They seem to get that quite well, but they miss information for extending git (maybe they don't want it).

Their idea of having a guide for designers and one for coders is great! (two target groups with entirely different needs).

Also the question What can I gain by using Mercurial? needs to be answered somehwere.

People who want to learn more about Mercurial

  1. Returning visitors. "What changed since my last visit?"
  2. Developers who want to try out workflows. "What else can I do with it?"
  3. People who want to understand Mercurial. "How does it work internally?"
  4. People who want to adapt Mercurial to their workflow. "How can I make Mercurial work for me?"
  5. People who want to contribute. "How can I help improve Mercurial with the skills I have?" or "How can I help Mercurial most efficiently - what should I go for?"
  6. People who have a specific need. "How can I find exactly this?"
  7. People that want to know how a DVCS can support their development workflows. "What makes DVCS better. which workflows can we/I use?"
  8. People who have heard something about Mercurial and want to verify that. "I heard xyz, is that true?" -> Common Myths about Mercurial

Group 5 needs a quick link to the most relevant extensions.

A specific need of group 6 could be "I heard about extension XY, where is it?" A FAQ should be a good starting point, as well as the search function and maybe a short list of very frequently asked questions.

People who are currently coding on Mercurial

They give additional momentum for the actual development

  • "How to do X?"
  • "Where and how can I tell others of my changes?"
  • "How can I send patches - how should I do them and how are their chances for being accepted?"

Second Step: Target Groups for Mercurial

Whom do we need to reach to best spread Mercurial?

This leads to a first question:

For whom is mercurial most useful?

Strengths of Mercurial: The view of People from the mercurial Mailing-List

This is an as of yet unsorted list of opinions from mercurial users. It still contains double entries and stuff. They are extracted from a thread in the mercurial list begun with the question: [http://article.gmane.org/gmane.comp.version-control.mercurial.general/11364 'What are the strengths of Mercurial for you?'] Pelase feel free to clean, sort and edit it.

The full list can be found on a seperate page.

The following list contains the number of times a feature was named in brackets after its description. It is sorted according to that number. Incidentally this also is the order most people named in their emails as their personal order of importance.

  • Cleanliness / Consistency; Does what it promises; Just works the way I expect; It simply works - very few surprises (10)
  • Fast (7)
  • Ease of use; Straightforward; Simplicity. (7)
  • Solid Windows support (command line and TortoiseHG) (5)
  • "hg serve", the easiest repository browser available! ; instant salesman for showing core concepts, what history looks like, etc (5)
  • MQ; Mercurial Queue (4)
  • TortoiseHG; The graph in it (3)
  • It is distributed and works offline (3)
  • Easy to learn; we liked the hg book; It took me one evening to get comfortable with it; Took less than an hour to understand it. (3)
  • Very nice community (3)
  • It's so easy to start a project (2)
  • Stability / Reliability; Append only repo model - hard to make any grave errors. (2)
  • Doesn't limit how I work (2)
  • Extensibility: Complex tasks can be done using extensions (2)
  • The devs are friendly (2)
  • Reasonably small codebase (2)
  • Stability in the underlying repo structure (2)
  • Works on many platforms; Fast on all platforms. (2)
  • Ease of deployment (2)

All the following points were named only once:

  • Very easy to use over HTTP.
  • hg help XXX always seems to have the information I need
  • Bugzilla integration
  • Core is extremely stable but there's lots of interesting developments as extensions
  • No repository maintenance
  • The template engine
  • It is easy to use & write extensions
  • Pretty backward compatible
  • bash completion
  • hg addremove --similarity
  • Only the .hg folder, no many .svn folders
  • Easy to setup extensions
  • Stable (no big changes in command syntax)
  • Utterly trivial to set up local clone redistribution points and backups.
  • zip/tar/etc archives
  • Mostly Python
  • Cheap branching
  • color diff
  • color status
  • merging uses my merge tool
  • Bundles
  • bisect
  • grep
  • GnuPG integration
  • Bookmarks
  • Philosophy (at all levels: project, design, community, etc.)
  • Focus
  • Syntax highlighting on the repo browser.
  • crecord extension

In which of these is Mercurial the top of the crowd?

To whom are these features most useful?

Who of those are most important for spreading Mercurial?

Who is most likely act as multiplicator or bring more developers to Mercurial?

Simpler: How many new users and developers do we expect to come from this group?

Which groups of people does Mercurial need for getting ever better?

And how do we get developers interested?

Some more ideas

You always need a section like this :)

  • dsop: It's probably out of scope for this discussion, but I keep thinking it'd be nice if there was some sort of "I'm using this" voting for extensions.
  • ArneBab: Another point for the Website: "Testimonials" (what people like about Mercurial). It would be great to find the reasons why the different projects chose Mercurial, and get them on the site.
  • Which target group consists of multiplicators who will pass Mercurial along? - that's something Git got somehow right: Integrators switch, then they push their devs to switch and those push users to switch. Which chain can Mercurial use?
  • We need a quick link to the Roadmap for people who want to see where Mercurial is headed to know if its direction fits their needs.
  • For each extension add links to workflows which use the extension.
  • Link to the wiki wherever possible. It's a great resource, and the website can provide the huge avantage of giving a nice portal to it while the wiki gives the website the advantage of being more up to date and not having to recreate and restructure all infromation. Any information which could also be in the wiki should be in the wiki (after the 1.9 release the MoinMoin team will work on the Storage framework, integrating the Mercurial backend, so it will grow far more convenient to use).
  • Tell example stories wherever possible to make every workflow and similar more accessible. If possible use real stories with real names and a link to a success story, E-Mail posting, quote or similar.
  • Since Mercurial appeals much to those who don't want to bother too much with their tool, we should provide quick well-founded counters to common arguments against Mercurial, so our users don't simply get overrun by overzealous git experts who don't really know Mercurial. This part needs examples more than any other part, maybe even scripts to directly show the arguments.
  • A planet.mercurial-scm.org site which aggregates Weblg entries about mercurial (encourages bloggers to write about mercurial and increases the information spread in the community as well as the comment ration in the weblogs).
  • A section "Mercurial for svn and cvs users". At least a link to this should be on the main page.
  • a section "Mercurial for git users" and one for Bazaar users. This can be deeper in the site, for example under "Refugees from other SCMs" maybe even directly the wiki page.
  • A section "Mercurial for graphic designers" or similar.
  • The guide for svn users should state that hg paths gives the remote path information and takes some part of the workload of svn info.
  • Quickly available information on how to write extensions (maybe directly on the front page): Every developer who joins in Extension writing increases Mercurials momentum.

Updated