Website improvements, part 1

[Urs Liska]

Hi all,

  [I have sent a message a few hours ago, but from a different email account.
   If this first email should go through nevertheless, the email you are reading
   now is the only relevant version.]

as should be known by now I'm currently reviewing the content of lilypond.org to make it more accessible to new users.
Originally I intended to clarify the command-line-enhanced-editor issue to avoid the double-click-on-lilypond.exe-doesn't-open-program misconception, but it seems to be necessary to do quite some more restructuring of the reading trail.

As one change leads to another this would easily lead to a complete rewrite of the website. And as I don't want to do that and confront you with a finished suggestion it's high time now to discuss what I've done so far.

This email has three parts:
a) my current result suggested for an informal review,
b) (technical) detail questions about them and
c) questions about what still has to be done.

I have discussed with Carl (Peterson) that it would be good to proceed with the following steps:
- get the proposed _content_ changes into a shape for a formal review.
  (Do this informally and incrementally so we'll have only one formal review in the end)
- Once that's clear Carl will work on a new appearance,
  taking into account if the content would require structural changes
- While he's working on that translators can try to update the website translations
- Finally everything should be released in one go.

###

a)
I've reviewed the "Introduction" section and the "Download" entry page.
I have always tried to keep as much in its current state. That is either leave it alone completely or relocate a subsection without changing it. But of course this wasn't always possible. So I would say: If I have touched any existing material I'm sure it had to be touched. But what I've done with it and what I've added may be influenced by my personal view on LilyPond.
A good part of what I'm presenting today has already been commented by Janek, so it's not _completely_ my homegrown stuff.

If you look at my suggestions, please try to see it as it is now and try not to consider what I changed.
I tried very hard to determine the type, amount and order of information someone would need who doesn't know about LilyPond, text input, a "compiled system" architecture etc., so please try also to ignore as much of your existing knowledge about these topics.

You can see the result of my work so far at http://openlilylib.org/lilyweb/introduction.html
I have uploaded all pages below "Introduction" plus download.html. They are displayed with the current CSS but without images. The links between the uploaded pages work as expected, while everything else obviously goes 404.

The commits leading to this are here: https://github.com/lilypond/lilypond/tree/urs/restructure-web.
(This branch is subject to be rebased at any point until further notice)

I have a few comments on my changes. Maybe you should first browse my pages and then read the comments.

- I changed "Easier editing" to "Editing".
  Actually this is what we're talking about.
  While technically "editing" means any editor and "easier editing" means dedicated tools
  this isn't a relevant distinction for the average (and particularly a new) user.
  What we want and what seems to have been the consensus on lilypond-user is to make
  clear that LilyPond itself isn't an editing environment but that the usual way (and the one
  that should be recommended on lilypond.org) to work with it is to install LilyPond itself
  and a dedicated tool in addition. Preferrably installing the tool which should in turn take
  care of installing LilyPond.

- I organized the entry scenario (= introduction.html) according to three questions
  (Janek's suggestion):
  - Why should I consider LilyPond?
  - How does it work?
  - Does it really work/what's the real-world use?
  This is reflected in the layout of the boxes on introduction.html
  while it's irrelevant in which direction the user proceeds from the "Why" box
- I sorted the page order (menu entries) according to that structure
- I've adapted the "Where now" boxes to reflect this order too,
  while at the same time offering a slightly more flexible reading path

- One page I restructured in particular is the "Features" page
  which I actually found quite unstructured. But also here I tried
  to keep as much in its original state as possible.

- I added a new page for the "What people did with LilyPond" gallery.
  Lacking a better name I labeled it "Appliances", please suggest
  better names. Actually it's about applications of LilyPond for other
  uses, but "Applications" would certainly raise wrong expectations.

###

b)
- I have added a few @anchor-s, particularly on the editing page.
  Adding an anchor to a @subheading creates an empty paragraph
  (as can be seen in the current draft),
  but linking to the implicit anchor that @subheading creates doesn't work
  and gives an error while generating the website.
  I'd be glad about any help here.

- I have moved the lilypond-book image on "Features" to another box
  because the corresponding text moved too.
- I have used an existing image instead for the "Text input" box.
  But this should either be scaled down or completely replaced with
  another image. Please suggest.

- It would be nice to distinguish external links somehow (with CSS).

c)

- I think we should mention MusicXML import somewhere near the start of
  the reading trail because that's an important feature for people coming
  from other programs. But I'm not sure where this would fit in best.
  Probably on the Features page.

- I think it would be good to add something about version control on the
  "Text input" page, but that's something I wouldn't want to do without
  prior discussion.

- Would you consider it useful/appropriate to link to
  http://lilypondblog.org/2013/07/plain-text-files-in-music/ somewhere?
  Either in the Text input box on "Features" or on "Text input"?

- I think the @contactUsAbout macro should be reconsidered.
  For what it's used in the Introduction section the requested procedure
  is way too complicated. If people want to let us know about "other
  productions/reviews/etc." they should simply write an email to somewhere.
  If someone clicks on the link (to, say, tell us about a concert or publication)
  the first he sees is: Please check our issues list.
  Then he is asked to read about Tiny examples to create a proper bug report.
  Only then he is told how to write to bug-lilypond.
  I suggest to say "... please let us know: If you are subscribed to the bug-lilypond
  mailing list you can send a message to address@hidden, otherwise you
  can post to this list using the gmane web interface."

- The structure of the "Community" section is, ehm, wild.
  I think it would be good to have an additional navigational layer.
  But before thinking about a structure I'd like to know if this would be accepted.

- I have one question about the structure of "Manuals":
  What the hell is this "Web" menu item for?
  If you follow this trail you'll either be directed to the homepage again
  or to a copy of the content on a different tree.
  _If_ there's a reason for this it definitely should be made clear somewhere
  otherwise this should be removed IMO.


That's it for now.
Urs