lilypond.org modification - informal review, first part

[openLilyLib]

Hi all,

as should be known by now I'm reviewing the content of lilypond.org to make it more accessible to new users.
Actually 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 present you 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 as an informal review,
b) (technical) detail questions about them and
c) questions about what still has to be done.

a)
I've reviewed the "Introduction" section and the "Download" entry page.
I have always tried to keep as much as it is. 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, os it's not _completey_ 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.

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 the 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 on the urs/restructure-web branch on https://github.com/lilypond/lilypond. (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 new) user.

- I organized the entry scenario 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 in its original state what was 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,
  but linking to the implicit anchor that @subheading creates doesn't work
  and gives an error while generating the website.

- I have moved the lilypond-book image on "Features" to the correct box
- 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
  because that's an important feature for people coming from other programs.
  But I'm not sure where this would fit in.

- 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 is generally acceptable.

- 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