Re: Website improvements, part 1

[Urs Liska]

Am 12.12.2013 04:19, schrieb Graham Percival:

On Wed, Dec 11, 2013 at 02:21:28PM +0100, Urs Liska wrote:

   - I changed "Easier editing" to "Editing".

ok.  I also like the "applicances" tab, although I agree with you
that the name might be ideal (but I also can't think of a better
name right now).

Just a bunch of ideas:
We're talking about
- Applications of LilyPond
- Use of LilyPond in different contexts
- "Abusing" LiylPond
- integrating LilyPond in other tools
- making LilyPond part of something else
- using LilyPond as an engine for other tools

Does this trigger any ideas for a menu/page title with anybody?

   - I organized the entry scenario (= introduction.html) according to three
   questions
     - Why should I consider LilyPond?

IMO "examples" should remain part of that.

Any more opinions on that?
My reasoning was:
- I think "Features->Background->Freedom" and then
  "How LilyPond works"
  is a good reading path
- "Examples" is similar to a "Screenshots" menu item in many websites
  and can be somewhat taken out of that intitial reading path
- I added the link to "Examples" to the "Where now?" box on "Features".
However, now I see that I would revert making "Background" link directly to the "Essay" manual because that would take the reader out of the reading path. (and my updated text on "Background" makes it easier to understand)

     - Does it really work/what's the real-world use?

I'd be fine with calling that box "LilyPond in the real world",
although I'm not certain if the applicances should be in this
category.  I mean, some of them make sense (like wikipedia), but
others seem like "toy" examples.

That's probably right, but we should hope to get more entries to that page in the future.
And even toy examples give an impression of the diversity of things you can do with LilyPond.
We've already covered "serious" use in Productions.
I have to say, the "Appliances" are more questionable after renaming the box as you suggest ;-)

If anything, I think that the "web frontends" should get their own
tab.

You mean the box from "Editing" should be raised to its own page, next to "Editing"?

     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

At the moment, the order seems to go top-left, bottom-left,
top-right, bottom-right.  

It is, although it was on purpose that after the first box you can actually go right _or_ down.

The general design of the website is to
go top-left, top-right, bottom-left, bottom-right.  I'm not
certain this is an important distinction, but it's worth
considering.  

OK, I considered it by clicking through the complete website (except the docs of course) and saw that there isn't any single comparable case.
Usually when we have two boxes side by side they are followed by a column-center box, so the flow is clear.
The only exception is on the Download subpages:
- on the Mac and Windows pages we have two short boxes left and one long box right.
  But they're not clearly defining a reading path but rather an alternative
- on the Unix page we also have two boxes left and one box right,
  but it's clear that it's going top-left, bottom-left, right.

So what to do with it?
Semantically it would be less ambiguous to use only one column for the Introduction page.
But that wouldn't look nice because the items are so short.
I could accept changing this order (i.e. exchange the boxes right-top and bottom-left), but I wouldn't consider it necessary - the ambiguity should be suitable for that page.

Any more opinions?

However, I still think that text input and editing
should be the final part of the introduction.

Please specify why you think so.
The incentive for reviewing of the website structure was (on lilypond-user) that too many people don't realize the basics of the compiled approach when visiting the website. Which causes too many people to get stuck when they're not able to "open LilyPond".
My goal was to strenghten the conceptual side in the default reading path by leading to these core concepts earlier.
As mentioned above I consider "Examples", "Productions" and "Appliances" more like an optional path.

   - 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.

I disagree.  The purpose of "text input" is to make potential
users realize that yes, we use text, but no, it's not too
complicated.  "Version control" is a complicated concept for
non-programmers which would dilute the previous message.  You
already mentioned version control on the Features page, which
should be sufficient.

Accepted. This is why I asked first in that case ;-)

   - I think the @contactUsAbout macro should be reconsidered.

I agree, you made good points here.

Please note that *this* is the kind of change that can be done
immediately, submitted for review, etc.  It doesn't need to wait
for James to finish his changes or 2.18 to be released.  I would
*heavily* encourage you to submit small improvements like this
soon, instead of combining them in a large reorganization that
creates havoc for translators.

OK. I thought that delivering a stream of consecutive patches would be an even heavier burden on translators.
But OK, I'll see to it.

Apart from the technical impact on the doc system, making small
changes like this reassure developers that you're serious and that
you know how the system works.

OK.
Then I should base a patch on current master, upload it and - assuming it will be accepted - mail the patch to someone (?) for pushing it?

From what I've done so far I think the following individual changes could also be uploaded independently:
- Adding an introductory text to "Download"
- Adding version numbers to Unix packages
- Clarify the text on "Background" page

More involved changes that I could nevertheless put up for review?
- Rename "Easier Editing" to "Editing"
  (does this affect translation more than other changes?)
- Updating the "Editing" page
  (split in two parts: reorganisation of items / rewording)
- Rewrite of the "Features" page

   - 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.

Probably not.  There's @chapters and @sections; having a bunch of
@subsections for one chapter is a bit weird.

Again: That's why I asked first.

I agree that Community is a bit wild; can you think of a division
that would split it into two chapters?

I will think about it and make an outline suggestion without actually writing anything.

   - I have one question about the structure of "Manuals":
     What the hell is this "Web" menu item for?

The website.  It's created as a pdf and info.  One of the very
early goals of the doc system is that all the information should
be present via only info or pdfs (i.e. without an internet
connection).

Hm.
While I can see the use of a downloadable website it is really, really irritating that you can (in the web browser) navigate to a "Web" manual that " supplies general information about LilyPond" and when you open that manual as "Web (split HTML)" as I'd do with any other manual you're suddenly on the homepage again - but not on the homepage but actually on a copy of it five directories below.

I think _something_ has to be done about this, but I'll open another thread for it to get a better understanding.

Urs

- Graham