Issue 40510046: Web: Download: Add introductory text
|
Created:
10 years, 4 months ago by uliska Modified:
10 years, 4 months ago CC:
lilypond-devel_gnu.org Visibility:
Public. |
DescriptionWeb: Download: Add introductory text
This addresses the initial issue discussed on lilypond-user:
too many people don't understand what they download and get
stuck on not being able to "open the LilyPond program".
Add a text that explains the compiled approach and makes clear
one should have LilyPond _and_ an editing environment.
The current warning (which apparently wasn't sufficient)
has been removed from this page but is kept on the subpages
in case someone reaches them by a direct link.
Patch Set 1 #
Total comments: 3
Patch Set 2 : Incorporate comments #
Total comments: 16
Patch Set 3 : Incorporating review comments #
Total comments: 4
MessagesTotal messages: 26
A couple of nitpicks, otherwise LGTM. https://codereview.appspot.com/40510046/diff/1/Documentation/web/download.itexi File Documentation/web/download.itexi (right): https://codereview.appspot.com/40510046/diff/1/Documentation/web/download.ite... Documentation/web/download.itexi:57: concept you'll find a list of known editors. For beginners it is "Beginners are recommended to ..." https://codereview.appspot.com/40510046/diff/1/Documentation/web/download.ite... Documentation/web/download.itexi:63: However, if you already have and editing environment and simply want "and" -> "an" https://codereview.appspot.com/40510046/diff/1/Documentation/web/download.ite... Documentation/web/download.itexi:64: to install a new LilyPond version you can proceed below. "proceed as described below."
Sign in to reply to this message.
Incorporate comments
Sign in to reply to this message.
Overall this is a bit too chatty for my liking. I have tried to give some constructive suggestions but please make sure that you follow the doc guidelines and use the appropriate Texinfo commands (as applicable). It fails make at the moment (I will see why from my patchy and update the Tracker accordingly) https://codereview.appspot.com/40510046/diff/20001/Documentation/web/download... File Documentation/web/download.itexi (right): https://codereview.appspot.com/40510046/diff/20001/Documentation/web/download... Documentation/web/download.itexi:38: Is this whole section conforming to the correct line length - 72 (or 66) chars? At least here in Rietveld it looks sloppy with weird line breaks. Maybe this is just the way it is displayed here but can we make sure please. https://codereview.appspot.com/40510046/diff/20001/Documentation/web/download... Documentation/web/download.itexi:40: @subheading Before you proceed ... I don't like those elipses and they aren't really needed (or being used correctly, they are for missing words and anyway there is a texinfo command for 'dots'.) can we just have 'Before you proceed' and be done? https://codereview.appspot.com/40510046/diff/20001/Documentation/web/download... Documentation/web/download.itexi:42: ... you should be aware of some facts and concepts. Remove this '... you should be aware of ...' line. Subheading is enough. https://codereview.appspot.com/40510046/diff/20001/Documentation/web/download... Documentation/web/download.itexi:50: If you want you can go to @ref{Text input} and learn more about LilyPond's What happens if they 'don't want?' Remove the 'If you want you can go to' Just keep it simple. I.e 'See @ref{Text input} to learn more.' https://codereview.appspot.com/40510046/diff/20001/Documentation/web/download... Documentation/web/download.itexi:53: @subsubheading I'm new to LilyPond and don't have a dedicated editor yet I personally don't like these 'first person' question-type headings, but if we have to have them can we just remove the 'I'm new to LilyPond' and get to the point. Something like 'Which dedicated LilyPond Editor' or similar. https://codereview.appspot.com/40510046/diff/20001/Documentation/web/download... Documentation/web/download.itexi:55: If you don't already have an editing environment for LilyPond you should You had already subheaded this section as '[I] ... don't have a dedicated editor...' so these first words are redundant. Just skip to the point. "See @ref{Editing} to find a list of LilyPond editors. Frescobaldi or Denemo are recommended for beginners." https://codereview.appspot.com/40510046/diff/20001/Documentation/web/download... Documentation/web/download.itexi:57: concept you'll find a list of known editors. Beginners are Two spaces after a full point. https://codereview.appspot.com/40510046/diff/20001/Documentation/web/download... Documentation/web/download.itexi:59: @strong{Denemo}. Both can take care of installing LilyPond for you. Two spaces after a full point https://codereview.appspot.com/40510046/diff/20001/Documentation/web/download... Documentation/web/download.itexi:64: to install a new LilyPond version you can proceed as described below. Is this section even needed?
Sign in to reply to this message.
Incorporated most of the comments. Will upload new patch set in a minute https://codereview.appspot.com/40510046/diff/20001/Documentation/web/download... File Documentation/web/download.itexi (right): https://codereview.appspot.com/40510046/diff/20001/Documentation/web/download... Documentation/web/download.itexi:38: On 2013/12/13 06:00:09, J_lowe wrote: > Is this whole section conforming to the correct line length - 72 (or 66) chars? > At least here in Rietveld it looks sloppy with weird line breaks. Maybe this is > just the way it is displayed here but can we make sure please. Done. https://codereview.appspot.com/40510046/diff/20001/Documentation/web/download... Documentation/web/download.itexi:40: @subheading Before you proceed ... On 2013/12/13 06:00:09, J_lowe wrote: > I don't like those elipses and they aren't really needed (or being used > correctly, they are for missing words and anyway there is a texinfo command for > 'dots'.) can we just have 'Before you proceed' and be done? I'm OK with this kind of edits. But I'd like to point out that I "copied" the "chatty" style from quite some existing texts on the website: Just a few examples: - "I want to see some music!" - "Yep, it's free." Done. https://codereview.appspot.com/40510046/diff/20001/Documentation/web/download... Documentation/web/download.itexi:42: ... you should be aware of some facts and concepts. On 2013/12/13 06:00:09, J_lowe wrote: > Remove this '... you should be aware of ...' line. Subheading is enough. Done. https://codereview.appspot.com/40510046/diff/20001/Documentation/web/download... Documentation/web/download.itexi:50: If you want you can go to @ref{Text input} and learn more about LilyPond's On 2013/12/13 06:00:09, J_lowe wrote: > What happens if they 'don't want?' Remove the 'If you want you can go to' > > Just keep it simple. I.e 'See @ref{Text input} to learn more.' Done. https://codereview.appspot.com/40510046/diff/20001/Documentation/web/download... Documentation/web/download.itexi:53: @subsubheading I'm new to LilyPond and don't have a dedicated editor yet On 2013/12/13 06:00:09, J_lowe wrote: > I personally don't like these 'first person' question-type headings, but if we > have to have them can we just remove the 'I'm new to LilyPond' and get to the > point. > > Something like 'Which dedicated LilyPond Editor' or similar. I think in this case we *should* get to this colloquial style. It seems to be necessary because too many people have got this wrong, presumably because they didn't really bother to read. However I've switched to a "You" address. Done. https://codereview.appspot.com/40510046/diff/20001/Documentation/web/download... Documentation/web/download.itexi:55: If you don't already have an editing environment for LilyPond you should On 2013/12/13 06:00:09, J_lowe wrote: > You had already subheaded this section as '[I] ... don't have a dedicated > editor...' so these first words are redundant. Just skip to the point. > > "See @ref{Editing} to find a list of LilyPond editors. Frescobaldi or Denemo are > recommended for beginners." Done. https://codereview.appspot.com/40510046/diff/20001/Documentation/web/download... Documentation/web/download.itexi:64: to install a new LilyPond version you can proceed as described below. On 2013/12/13 06:00:09, J_lowe wrote: > Is this section even needed? I think yes. This should step in the way of a new user who'd (out of a habit) jump directly to the Download buttons.
Sign in to reply to this message.
Incorporating review comments
Sign in to reply to this message.
https://codereview.appspot.com/40510046/diff/40001/Documentation/web/download... File Documentation/web/download.itexi (left): https://codereview.appspot.com/40510046/diff/40001/Documentation/web/download... Documentation/web/download.itexi:35: @warningTextBased Umm, isn't the whole point of this to be a warning? Why are you removing the warning CSS tag? https://codereview.appspot.com/40510046/diff/40001/Documentation/web/download... File Documentation/web/download.itexi (right): https://codereview.appspot.com/40510046/diff/40001/Documentation/web/download... Documentation/web/download.itexi:42: LilyPond is a @strong{command line application} translating That's very chatty. Did all the people complaining about this fail to notice the existing warning? Perhaps the CSS for the warning box should be light red, instead of adding more text. I mean, if people didn't read the existing text, then adding more is unlikely to help.
Sign in to reply to this message.
https://codereview.appspot.com/40510046/diff/40001/Documentation/web/download... File Documentation/web/download.itexi (left): https://codereview.appspot.com/40510046/diff/40001/Documentation/web/download... Documentation/web/download.itexi:35: @warningTextBased On 2013/12/14 03:51:33, Graham Percival wrote: > Umm, isn't the whole point of this to be a warning? Why are you removing the > warning CSS tag? It's the whole point of this patch to raise this information to the level of regular website text. https://codereview.appspot.com/40510046/diff/40001/Documentation/web/download... File Documentation/web/download.itexi (right): https://codereview.appspot.com/40510046/diff/40001/Documentation/web/download... Documentation/web/download.itexi:42: LilyPond is a @strong{command line application} translating On 2013/12/14 03:51:33, Graham Percival wrote: > That's very chatty. Did all the people complaining about this fail to notice > the existing warning? > > Perhaps the CSS for the warning box should be light red, instead of adding more > text. I mean, if people didn't read the existing text, then adding more is > unlikely to help. We may discuss about wording details, but I'm sure the general idea of this patch is the right one. From discussion in several quite diversified threads on lilypond-user it became clear that people (i.e. potential new users) have to get a clearer picture of what LilyPond and its infrastructure essentially are. This was the whole idea of starting a website review. I believe that this *will* require some "chattiness" (or put differently: some more elaborate explanations) here and there. And I'm sure it was consensus that the path to reading what LilyPond is and what you need to get it running should be made more explicit on the Download page. (Together with renaming and an introductory text on the "Easier Editing" page, which will be one of my next patches). I don't think making the "Note" more visible will help with the fact that people reaching the homepage, then click on "Download" get the right picture from it. I think a regular box with "Before you proceed" and the second stopper "You just wnat a new version?" will be more effective than a warning box.
Sign in to reply to this message.
On Sat, Dec 14, 2013 at 09:46:54AM +0000, lilyliska@googlemail.com wrote: > > On 2013/12/14 03:51:33, Graham Percival wrote: > >Umm, isn't the whole point of this to be a warning? Why are you > removing the > >warning CSS tag? > > It's the whole point of this patch to raise this information to the > level of regular website text. Why? So that it's not as obvious? I imagine two situations in which people download the binary without knowing what they're getting. 1) they didn't notice the existing warning. Solution: change the CSS to make it more prominent. 2) they noticed the existing, read the "text input" page, but were still confused. Solution: improve the "text input" page. Was it clear from the discussion on -user which of those problems it was? > From discussion in several quite diversified threads on lilypond-user it > became clear that people (i.e. potential new users) have to get a > clearer picture of what LilyPond and its infrastructure essentially are. > This was the whole idea of starting a website review. Ok. That should be done in the introduction. Maybe more images on the Text input page? Maybe another whole page about "sample usage", or something like that? ... wait a moment, doesn't the Windows download page include screenshots of how to use the lilypond binary? Did people fail to notice those screenshots? > I don't think making the "Note" more visible will help with the fact > that people reaching the homepage, then click on "Download" get the > right picture from it. I think a regular box with "Before you proceed" > and the second stopper "You just wnat a new version?" will be more > effective than a warning box. I'm fine with rewording the warning box. Text like "before you proceed" might be good. However, I'm *not* fine with reproducing a bunch of explanations about how lilypond works. We have a place to explain that: the introduction. Either people aren't finding "Text input", or "Text input" needs work. - Graham
Sign in to reply to this message.
Am 15.12.2013 06:47, schrieb Graham Percival: > On Sat, Dec 14, 2013 at 09:46:54AM +0000, lilyliska@googlemail.com wrote: >> >> On 2013/12/14 03:51:33, Graham Percival wrote: >>> Umm, isn't the whole point of this to be a warning? Why are you >> removing the >>> warning CSS tag? >> >> It's the whole point of this patch to raise this information to the >> level of regular website text. > > Why? So that it's not as obvious? No. So that it's obvious on a different level. > I imagine two situations in > which people download the binary without knowing what they're > getting. > > 1) they didn't notice the existing warning. Solution: change the > CSS to make it more prominent. I don't think that a warning is the right approach in that context. Most users will take a warning as a kind of side note, and if it doesn't look crucial (like "this may break your system" or "Works only on Ubuntu 13.10 or later") they may put it aside for later consideration (if at all). Of course this is an opinion I can't prove formally. If you say: It's all there, people should read it or should be forced to read it I can't formally object. Nevertheless I'm convinced that the approach should be modified. > > 2) they noticed the existing, read the "text input" page, but were > still confused. Solution: improve the "text input" page. I think the only issue with "text input" might be that it isn't explicit (or rather suggestive) enough about the editing environment. > > Was it clear from the discussion on -user which of those problems > it was? Not unambiguously clear. But it seems clear that we will have to take into account that people will proceed directly to the Download page without reading anything of the introduction or the Features page at most. > >> From discussion in several quite diversified threads on >> lilypond-user it >> became clear that people (i.e. potential new users) have to get a >> clearer picture of what LilyPond and its infrastructure essentially are. >> This was the whole idea of starting a website review. > > Ok. That should be done in the introduction. Maybe more images > on the Text input page? No, that page is good IMO. > Maybe another whole page about "sample > usage", or something like that? I think I've already made a suggestion in this regard: Rename "Easier editing" to "Editing" and add an introduction there. "Text input" and "Editing environments" are two concepts that have to be made explicit independently. I think the text input is explained very well, but the editing aspect is somewhat blurred, one could even perceive it as somewhat bashfully belittled. Maybe this should even be split: One dedicated page explaining the concept of IDEs, similar to the Text Input page but less elaborate, and another page that more or less lists available editors (i.e. the current "Easier editing" page with some modifications). > > ... wait a moment, doesn't the Windows download page include > screenshots of how to use the lilypond binary? Did people fail to > notice those screenshots? Probably they fail to draw the right conclusions from it. > >> I don't think making the "Note" more visible will help with the fact >> that people reaching the homepage, then click on "Download" get the >> right picture from it. I think a regular box with "Before you proceed" >> and the second stopper "You just wnat a new version?" will be more >> effective than a warning box. > > I'm fine with rewording the warning box. Text like "before you > proceed" might be good. However, I'm *not* fine with reproducing > a bunch of explanations about how lilypond works. We have a place > to explain that: the introduction. Either people aren't finding > "Text input", or "Text input" needs work. It was consensus that new users should actively be encouraged to download one of the complete environments, namely Frescobaldi or Denemo, which would then take care of installing LilyPond. Denemo already has LilyPond bundled, and Frescobaldi will/can be made to download and install LilyPond if needed. The "Download" page *is* the right place for this IMO. And the regular text of that page. ### I think the considerations about "chattiness" of texts or redundancy of information are suitable and necessary for the docs, but much less for the website. The website doesn't have to be redundancy-free document with every information exactly once and in the right place (which it is far from currently BTW). It should rather be a comfortable place for potential new users who aren't already familiar with LilyPond or text based toolchains in general. If that requires some redundancy or colloquial style then it should have it. One problem with the current website is that it contains too much content which is clearly written from a developer's perspective. I have invested a considerable amount of energy and time to review the site by taking the POV of our target audience. This resulted in a first set of suggestions but there would also have to be considerable follow-up work, for example reworking the Community chapter. I'm worried about the opposition even my first modest suggestions raise. There will be patches with more involved changes to come. And if each tiny bit is discussed to death from exactly the developer's perspective that seems part of the problem, I'll surely consider it an inappropriate use of my time quite soon. Urs > > - Graham > > _______________________________________________ > lilypond-devel mailing list > lilypond-devel@gnu.org > https://lists.gnu.org/mailman/listinfo/lilypond-devel >
Sign in to reply to this message.
Urs, On 15/12/13 12:23, Urs Liska wrote: > > > I'm worried about the opposition even my first modest suggestions raise. > There will be patches with more involved changes to come. And if each > tiny bit is discussed to death from exactly the developer's > perspective that seems part of the problem, I'll surely consider it an > inappropriate use of my time quite soon. You will need to be prepared for this kind of back and forth when doing anything significant with regard to Documentation. I have good experience of this. This is why Graham et al, always recommend to do small incremental changes, see https://codereview.appspot.com/4124056/ This took me 4 months to get consensus. Mainly because I picked this up from another Developer who had also (like I fear you are going to) gave up from 'comment fatigue' but the changes were massive. Just remember it isn't because we don't care what you think or want :) it's because we care _too much_ that some doc edits (and web includes this) takes time and needs discussion. James
Sign in to reply to this message.
Am 15.12.2013 14:14, schrieb James: > Urs, > > On 15/12/13 12:23, Urs Liska wrote: >> >> >> I'm worried about the opposition even my first modest suggestions raise. >> There will be patches with more involved changes to come. And if each >> tiny bit is discussed to death from exactly the developer's >> perspective that seems part of the problem, I'll surely consider it an >> inappropriate use of my time quite soon. > > You will need to be prepared for this kind of back and forth when doing > anything significant with regard to Documentation. I know that and I'm prepared, but I'm only willing to a certain extent to let this overtake my work and my attitude towards LilyPond. > ... > > Just remember it isn't because we don't care what you think or want :) > it's because we care _too much_ that some doc edits (and web includes > this) takes time and needs discussion. I know that and I fully agree that it's important to be somewhat strict about what comes into LilyPond or its parts. And I also see that not _each_ of my patches is objected against. But it's actually quite off-putting when you prepare a patch that is more or less based on a broad (and astonishingly productive) discussion on lilypond-user, and then (after two steps of fine-tuning) someone steps out and asks "why are you doing this?". (This is not personal against Graham because I know next it might be someone else.) Viewed from the very narrow perspective of the actual patch there isn't much I can argue against "People should read Text Input and if they don't we can't help them/we should help them find that page" or "this kind of stuff should conceptually be dealt with in the "Introduction" chapter". But actually my work and suggestions should be considered in the context of an overall "user experience on lilypond.org", that's why I offered a set of drafts to be read online. From there I was directed to propose small, "atomic" patches, and now we're in wrangles about details. It's out of proportion given the state some portions of the website are in currently. I don't want to imagine what happens if I propose my rewrite of the Features page (http://www.openlilylib.org/lilyweb/features.html). Urs > > James
Sign in to reply to this message.
Urs Liska <ul@openlilylib.org> writes: > I know that and I fully agree that it's important to be somewhat > strict about what comes into LilyPond or its parts. Yes and no. One wants to avoid unpleasant surprises. > And I also see that not _each_ of my patches is objected against. Well, it's basically one of the most visible parts of LilyPond. And everybody is qualified for an _opinion_ about that. In contrast, bad code often sneaks in and is discovered months later. The web site is basically immediate, is seen by tens of thousands of people, and is translated by all the translators. So it saves a _lot_ of trouble to get it right the first time. > But it's actually quite off-putting when you prepare a patch that is > more or less based on a broad (and astonishingly productive) > discussion on lilypond-user, and then (after two steps of fine-tuning) > someone steps out and asks "why are you doing this?". (This is not > personal against Graham because I know next it might be someone else.) Yes. It is a major part of review processes that a) some people come late into the game b) the preceding discussion on the user list is isolated from the actual patch review process. c) people have different opinions. It is also the nature of electronic communication that every "opponent" feels more or less like the same person. If one sees a similar objection repeated times, one tends to get annoyed even though it may just be an independent opinion. > Viewed from the very narrow perspective of the actual patch there > isn't much I can argue against "People should read Text Input and if > they don't we can't help them/we should help them find that page" or > "this kind of stuff should conceptually be dealt with in the > "Introduction" chapter". It's input. In the end, most of the decisions remain with the people who do the actual work. If you disagree with particular input, there is nothing wrong with saying so. If you find that three people tell you something in a row, then it may be worth figuring out what the underlying reason might be. On the one hand, it may be unfortunate that not everybody reads up on everything before voicing an opinion. On the other hand, this helps a bit with weighing some input. If you need a discussion for three people in a row to see your point, chances are that you would need a discussion to make a user visiting the web site see your point. But you won't get a discussion: they just go away. So just treat it as input. It's easy to fall into the trap of seeing it as a controverse, meaning that people try to defend a standpoint that only became fixed by the want to differentiate oneself from somebody else. It's a trap that I see myself in often. And it has happened a few times that I convinced somebody with compelling arguments that a proposal of his was a bad idea and technically infeasible. Only to implement it half a year later. It's usually in the area of "user interface" that something like this happens, and a web site is a user interface in some manner. > But actually my work and suggestions should be considered in the > context of an overall "user experience on lilypond.org", that's why I > offered a set of drafts to be read online. From there I was directed > to propose small, "atomic" patches, and now we're in wrangles about > details. It's out of proportion given the state some portions of the > website are in currently. Perhaps. The point is that this state has been there for a while, and all the translation work on it has already been done. Another point is that the mode of operation of LilyPond tends to attracts a breed of perfectionists that can be positively unstandable when occuring in groups. > I don't want to imagine what happens if I propose my rewrite of the > Features page (http://www.openlilylib.org/lilyweb/features.html). Let me tell you: it's not really that more satisfactory to get no feedback at all. That's what happens with the majority of my patches. It might also be due to people a) trusting my judgment b) not being eager to involve themselves in a discussion with me. You can expect a rather mixed bag of responses overall: sometimes you get more than you ask for, sometimes nothing at all. Getting more feedback often turns out more directly nettling at least to me, but sometimes the perceived annoyance does lead to changed solutions that, if one is honest about it, are an improvement over the original proposal. That's a lot of verbiage: the main point being that people take an active interest in the work you are now doing and which has not been worked on for a while, or worked on with different goals and perspectives and views and strategies, and those goals, perspectives and views and strategies were the result of a lot of thought and discussion. And even if one has to face that this thought and discussion failed to converge to an optimal solution, it's not gone in just a moment, and the intent is not all wrong, but probably just prioritized badly. Rewriting texts in this context can be tiresome; code and website layout have fewer variables to have an opinion about, in contrast. Thanks for caring. -- David Kastrup
Sign in to reply to this message.
On Sun, Dec 15, 2013 at 07:48:28PM +0100, David Kastrup wrote: > Urs Liska <ul@openlilylib.org> writes: > > > But it's actually quite off-putting when you prepare a patch that is > > more or less based on a broad (and astonishingly productive) > > discussion on lilypond-user, and then (after two steps of fine-tuning) > > someone steps out and asks "why are you doing this?". (This is not > > personal against Graham because I know next it might be someone else.) > > Yes. It is a major part of review processes that > > a) some people come late into the game > b) the preceding discussion on the user list is isolated from the actual > patch review process. I want to emphasize these points. The whole review process was put into place to encourage the senior developers to stick around and at least give comments on patches. There's still a ton of design decisions that are only known to the people who originally wrote that code or document. The goal is to allow & encourage those people (which I guess include me now) to pass along reasons why they made the decisions they did. If patches were accepted and pushed within a day, the senior devs might not have a chance to reply, and then give up on providing any input at all. Having a "patch countdown" of 48 hours or more, with no "penalty" for people coming "late" to the discussion (provided it's still within 48 hours), is a trade-off of encouraging senior devs to comment vs. encouraging new developers to make lots of changes. Of course, I'm not clamining that the design decisions of previous developers are necessarily correct. Maybe after discussing it with them, the community decides that it's worth breaking the previous architecture plan. But I think that discussion is well worth having. > > I don't want to imagine what happens if I propose my rewrite of the > > Features page (http://www.openlilylib.org/lilyweb/features.html). A rewrite of a single page has less impact than changing the intended flow of a new reader through the website. My only problem with your proposed Features page is that it changes the flow (i.e. the "where now?" box at the bottom). If you changed it back to the original "where now?" box, I'd have no problem with that new Features page. Cheers, - Graham
Sign in to reply to this message.
On Mon, Dec 16, 2013 at 11:29:44AM +0800, Graham Percival wrote: > > Urs Liska <ul@openlilylib.org> writes: > > > I don't want to imagine what happens if I propose my rewrite of the > > > Features page (http://www.openlilylib.org/lilyweb/features.html). > > A rewrite of a single page has less impact than changing the > intended flow of a new reader through the website. My only > problem with your proposed Features page is that it changes the > flow (i.e. the "where now?" box at the bottom). If you changed it > back to the original "where now?" box, I'd have no problem with > that new Features page. Oops, there is one problem with that new Features page. You wrote: Read more on the _Community_ pages. with the link on _Community_. This is not encouraged with texinfo, because that _Community_ link will be hard to read in the pdf version. Instead, please reword the sentence so that the link is at the end of the sentence (as you've done everywhere else on that page). Cheers, - Graham
Sign in to reply to this message.
On Sun, Dec 15, 2013 at 01:23:51PM +0100, Urs Liska wrote: > Am 15.12.2013 06:47, schrieb Graham Percival: > >2) they noticed the existing, read the "text input" page, but were > >still confused. Solution: improve the "text input" page. > > I think the only issue with "text input" might be that it isn't > explicit (or rather suggestive) enough about the editing > environment. Then it should be fixed. > >Was it clear from the discussion on -user which of those problems > >it was? > > Not unambiguously clear. But it seems clear that we will have to > take into account that people will proceed directly to the Download > page without reading anything of the introduction or the Features > page at most. Hence the warning. > >Maybe another whole page about "sample > >usage", or something like that? > > Maybe this should even be split: One dedicated page explaining the > concept of IDEs, similar to the Text Input page but less elaborate, > and another page that more or less lists available editors (i.e. the > current "Easier editing" page with some modifications). I like that idea. So there would be 3 pages in Introduction: - lilypond is text input - text input means you write text - list of available editors > It was consensus that new users should actively be encouraged to > download one of the complete environments, namely Frescobaldi or > Denemo, which would then take care of installing LilyPond. Is Frescobaldi available on OSX? It's lacking the appropriate symbol on the easier-editing page. ... apparently it's only available in macports. That isn't something that we should ask most users to try. Denemo is not available on FreeBSD or OSX (accoring to the symbols) so we can't recommend it without deliberately ignoring some users. Granted, anybody using freebsd will already know how things work, but we shouldn't ignore OSX users, particularly since many composers prefer OSX. > I think the considerations about "chattiness" of texts or redundancy > of information are suitable and necessary for the docs, but much > less for the website. I think that suitable chattiness is even *more* important for the website. Adding text is the easiest thing to do to docs, but can often make users turn off their brains and not read stuff. My rule of thumb is that doubling the text results in half the number of people reading it. > The website doesn't have to be redundancy-free document with every > information exactly once and in the right place (which it is far > from currently BTW). It should rather be a comfortable place for > potential new users who aren't already familiar with LilyPond or > text based toolchains in general. Right. So let's direct new users to the best explanation we have for how lilypond works. Not a 3-sentence summary of the situation. Direct them to a whole page with images, examples, screenshots, video screencasts, embedded youtube videos, etc. If somebody is unfamiliar with text input, you cannot give a good explanation in 3 sentences that they will understand. You can't, I can't, nobody can. It's a whole different concept. Sure, we could add 3 pages of material to the top of the download page (and presumably the top of the Windows download page as well). But that would annoy experienced users. Solution: use a short notice to get newbies onto a dedicated page for them. - Graham
Sign in to reply to this message.
On Dec 16, 2013 12:16 AM, "Graham Percival" <graham@percival-music.ca> wrote: > > On Sun, Dec 15, 2013 at 01:23:51PM +0100, Urs Liska wrote: > > It was consensus that new users should actively be encouraged to > > download one of the complete environments, namely Frescobaldi or > > Denemo, which would then take care of installing LilyPond. > > Is Frescobaldi available on OSX? It's lacking the appropriate > symbol on the easier-editing page. > ... apparently it's only available in macports. That isn't > something that we should ask most users to try. > > Denemo is not available on FreeBSD or OSX (accoring to the > symbols) so we can't recommend it without deliberately ignoring > some users. Granted, anybody using freebsd will already know how > things work, but we shouldn't ignore OSX users, particularly since > many composers prefer OSX. > Just thinking out loud here...would it be worth looking into tweaking the .htaccess file to do OS-based redirection on the download page, like many sites do? That way, if someone requests download.html, they are redirected to download-win.html if the server detects Windows, download-mac.html if it dectects OS X, download-nix.html for *nix, and so on, with download-all.html being the current page (and .htaccess silently redirecting here if there is no OS match). This would allow us to put all the information on one page for an operating system and recommend or not based on what is actually available. Carl P.
Sign in to reply to this message.
On Mon, Dec 16, 2013 at 12:42:16AM -0500, Carl Peterson wrote: > Just thinking out loud here...would it be worth looking into tweaking the > .htaccess file to do OS-based redirection on the download page, like many > sites do? That's possible, but having the unified landing page lets us include the software license, sponsors, and pointers to source code, old downloads, and devel versions. We could add those to all the individual pages, of course, but I don't think it's worth changing that much. - Graham
Sign in to reply to this message.
Am 16.12.2013 04:31, schrieb Graham Percival: > On Mon, Dec 16, 2013 at 11:29:44AM +0800, Graham Percival wrote: >>> Urs Liska <ul@openlilylib.org> writes: >>>> I don't want to imagine what happens if I propose my rewrite of the >>>> Features page (http://www.openlilylib.org/lilyweb/features.html). >> >> A rewrite of a single page has less impact than changing the >> intended flow of a new reader through the website. My only >> problem with your proposed Features page is that it changes the >> flow (i.e. the "where now?" box at the bottom). If you changed it >> back to the original "where now?" box, I'd have no problem with >> that new Features page. > > Oops, there is one problem with that new Features page. You > wrote: > Read more on the _Community_ pages. > with the link on _Community_. This is not encouraged with > texinfo, because that _Community_ link will be hard to read in the > pdf version. Instead, please reword the sentence so that the link > is at the end of the sentence (as you've done everywhere else on > that page). I didn't know that, sorry. Maybe because I never used pdf manuals. Urs > > Cheers, > - Graham >
Sign in to reply to this message.
Carl Peterson <carlopeterson@gmail.com> writes: > On Dec 16, 2013 12:16 AM, "Graham Percival" <graham@percival-music.ca> > wrote: >> >> On Sun, Dec 15, 2013 at 01:23:51PM +0100, Urs Liska wrote: >> > It was consensus that new users should actively be encouraged to >> > download one of the complete environments, namely Frescobaldi or >> > Denemo, which would then take care of installing LilyPond. >> >> Is Frescobaldi available on OSX? It's lacking the appropriate >> symbol on the easier-editing page. >> ... apparently it's only available in macports. That isn't >> something that we should ask most users to try. >> >> Denemo is not available on FreeBSD or OSX (accoring to the >> symbols) so we can't recommend it without deliberately ignoring >> some users. Granted, anybody using freebsd will already know how >> things work, but we shouldn't ignore OSX users, particularly since >> many composers prefer OSX. >> > > Just thinking out loud here...would it be worth looking into tweaking the > .htaccess file to do OS-based redirection on the download page, like many > sites do? That way, if someone requests download.html, they are redirected > to download-win.html if the server detects Windows, download-mac.html if it > dectects OS X, download-nix.html for *nix, and so on, with > download-all.html being the current page (and .htaccess silently > redirecting here if there is no OS match). This would allow us to put all > the information on one page for an operating system and recommend or not > based on what is actually available. No, based on what computer is used for downloading. That's more than often sufficiently different to make this a nuisance. What we could attempt doing is to move the entry for the purportedly detected operating system to the top. -- David Kastrup
Sign in to reply to this message.
Am 15.12.2013 19:48, schrieb David Kastrup: > Urs Liska <ul@openlilylib.org> writes: > ... >> Viewed from the very narrow perspective of the actual patch there >> isn't much I can argue against "People should read Text Input and if >> they don't we can't help them/we should help them find that page" or >> "this kind of stuff should conceptually be dealt with in the >> "Introduction" chapter". > > It's input. In the end, most of the decisions remain with the people > who do the actual work. If you disagree with particular input, there is > nothing wrong with saying so. > > If you find that three people tell you something in a row, then it may > be worth figuring out what the underlying reason might be. On the one > hand, it may be unfortunate that not everybody reads up on everything > before voicing an opinion. On the other hand, this helps a bit with > weighing some input. If you need a discussion for three people in a row > to see your point, chances are that you would need a discussion to make > a user visiting the web site see your point. But you won't get a > discussion: they just go away. OK, I see your point. But it's not the case here. It was only one discussion. In the meantime discussion has broadened through several more contributions. > > So just treat it as input. It's easy to fall into the trap of seeing it > as a controverse, meaning that people try to defend a standpoint that > only became fixed by the want to differentiate oneself from somebody > else. > > It's a trap that I see myself in often. And it has happened a few times > that I convinced somebody with compelling arguments that a proposal of > his was a bad idea and technically infeasible. Only to implement it > half a year later. It's usually in the area of "user interface" that > something like this happens, and a web site is a user interface in some > manner. > >> But actually my work and suggestions should be considered in the >> context of an overall "user experience on lilypond.org", that's why I >> offered a set of drafts to be read online. From there I was directed >> to propose small, "atomic" patches, and now we're in wrangles about >> details. It's out of proportion given the state some portions of the >> website are in currently. > > Perhaps. The point is that this state has been there for a while, and > all the translation work on it has already been done. Yes, most people don't think about it. We who are familiar with LilyPond have got used to finding our way to what we currently need, and take the existing website for granted. >> I don't want to imagine what happens if I propose my rewrite of the >> Features page (http://www.openlilylib.org/lilyweb/features.html). > > Let me tell you: it's not really that more satisfactory to get no > feedback at all. That's what happens with the majority of my patches. > It might also be due to people a) trusting my judgment b) not being > eager to involve themselves in a discussion with me. Probably both, in changing proportions. And maybe add c) not really understanding and therefore preferring not to get their feet wet. > > You can expect a rather mixed bag of responses overall: sometimes you > get more than you ask for, sometimes nothing at all. Getting more > feedback often turns out more directly nettling at least to me, but > sometimes the perceived annoyance does lead to changed solutions that, > if one is honest about it, are an improvement over the original > proposal. > > That's a lot of verbiage: the main point being that people take an > active interest in the work you are now doing and which has not been > worked on for a while, or worked on with different goals and > perspectives and views and strategies, and those goals, perspectives and > views and strategies were the result of a lot of thought and discussion. Plus partly the result of "historic" growth, adding something here and there and not cleaning up (cf. GSoC 2012) and presumably other stuff on the Community pages. > > And even if one has to face that this thought and discussion failed to > converge to an optimal solution, it's not gone in just a moment, and the > intent is not all wrong, but probably just prioritized badly. > > Rewriting texts in this context can be tiresome; code and website layout > have fewer variables to have an opinion about, in contrast. > > Thanks for caring. > Thanks for your well-balanced comments and thoughts (this also goes for those I didn't reply to). Urs
Sign in to reply to this message.
Am 16.12.2013 04:29, schrieb Graham Percival: >>> I don't want to imagine what happens if I propose my rewrite of the >>> > >Features page (http://www.openlilylib.org/lilyweb/features.html). > A rewrite of a single page has less impact than changing the > intended flow of a new reader through the website. My only > problem with your proposed Features page is that it changes the > flow (i.e. the "where now?" box at the bottom). If you changed it > back to the original "where now?" box, I'd have no problem with > that new Features page. > > Cheers, > - Graham As said in the other thread I'm not sure if we're completely "through" with that. But of course the "Where now?" box on this page has to be consistent with the overall structure. Urs
Sign in to reply to this message.
Am 16.12.2013 06:15, schrieb Graham Percival: > On Sun, Dec 15, 2013 at 01:23:51PM +0100, Urs Liska wrote: >> Am 15.12.2013 06:47, schrieb Graham Percival: >>> 2) they noticed the existing, read the "text input" page, but were >>> still confused. Solution: improve the "text input" page. >> >> I think the only issue with "text input" might be that it isn't >> explicit (or rather suggestive) enough about the editing >> environment. > > Then it should be fixed. OK. I think this can be a very small patch, and I'll give it a try. After https://codereview.appspot.com/40570043/ has been pushed. > >>> Was it clear from the discussion on -user which of those problems >>> it was? >> >> Not unambiguously clear. But it seems clear that we will have to >> take into account that people will proceed directly to the Download >> page without reading anything of the introduction or the Features >> page at most. > > Hence the warning. I'm still not sure whether the current "Note" (be it restyled or not) is better to "embrace" the user than a regular text box. But I suggest to postpone this whole issue and do a few other things first (see below) because they might change our view with regard to the "Download" landing page. (I.e. I'd "revoke" the patch and upload a few other ones first, when these are settled I'll/we'll review the state of the Download page.) > >>> Maybe another whole page about "sample >>> usage", or something like that? >> >> Maybe this should even be split: One dedicated page explaining the >> concept of IDEs, similar to the Text Input page but less elaborate, >> and another page that more or less lists available editors (i.e. the >> current "Easier editing" page with some modifications). > > I like that idea. So there would be 3 pages in Introduction: > - lilypond is text input Which would be more or less the current "Text input" page plus a small patch as mentioned above. > - text input means you write text Which I suggest to be named "Editing". > - list of available editors which should be called "Editors" or "Editing environments"??? > > >> It was consensus that new users should actively be encouraged to >> download one of the complete environments, namely Frescobaldi or >> Denemo, which would then take care of installing LilyPond. Actually there already is an issue for it: https://code.google.com/p/lilypond/issues/detail?id=3716 > > Is Frescobaldi available on OSX? It's lacking the appropriate > symbol on the easier-editing page. > ... apparently it's only available in macports. That isn't > something that we should ask most users to try. https://github.com/dliessi/ports/blob/master/INSTALL-Frescobaldi.md is the current installation instruction for OSX. I can't tell what this actually implies, but maybe it really isn't suitable as a "first choice" recommendation. > > Denemo is not available on FreeBSD or OSX (accoring to the > symbols) so we can't recommend it without deliberately ignoring > some users. Granted, anybody using freebsd will already know how > things work, but we shouldn't ignore OSX users, particularly since > many composers prefer OSX. According to http://denemo.org/downloads-page/ Denemo is available on Linux, Mac and Windows. So I'm not sure what that all means: Can we recommend it, particularly for first-time users? And if not, what should we recommend instead? We definitely want new users to have a path to a at least partially comfortable first editing environment. That was the initial motivation for all this discussion. Particularly for Windows users it is not acceptable that they're confronted with LilyPad alone which doesn't even offer syntax highlighting plus a Desktop icon that doesn't behave as Windows programs usually do. It wasn't absolutely decided (although I think there's no other option) that LilyPond can't be responsible for installing third party tools. The idea was rather to point to these third party tools - and if these were able to care for installing LilyPond, even better. So: Is there any acceptable environment available that we can recommend for all OSs? This could be to some extent discussed on a new "Editing" page, i.e. not on the top of the Download page and only very shortly on the Editors list page. Somthing along the lines of "on Windows you can use Frescobaldi or Denemo, on Mac OSX too, but Frescobaldi installation is more involved there etc." > >> I think the considerations about "chattiness" of texts or redundancy >> of information are suitable and necessary for the docs, but much >> less for the website. > > I think that suitable chattiness is even *more* important for the > website. Adding text is the easiest thing to do to docs, but can > often make users turn off their brains and not read stuff. My > rule of thumb is that doubling the text results in half the number > of people reading it. > >> The website doesn't have to be redundancy-free document with every >> information exactly once and in the right place (which it is far >> from currently BTW). It should rather be a comfortable place for >> potential new users who aren't already familiar with LilyPond or >> text based toolchains in general. > > Right. So let's direct new users to the best explanation we have > for how lilypond works. Not a 3-sentence summary of the > situation. Direct them to a whole page with images, examples, > screenshots, video screencasts, embedded youtube videos, etc. > If somebody is unfamiliar with text input, you cannot give a good > explanation in 3 sentences that they will understand. You can't, > I can't, nobody can. It's a whole different concept. > > Sure, we could add 3 pages of material to the top of the download > page (and presumably the top of the Windows download page as > well). But that would annoy experienced users. Solution: use a > short notice to get newbies onto a dedicated page for them. So I'll go ahead and make suggestions along the lines discussed here. Maybe the need for my original patch will have vanished by that or at least significantly changed. Urs > > - Graham >
Sign in to reply to this message.
On Mon, Dec 16, 2013 at 4:25 AM, David Kastrup <dak@gnu.org> wrote: > Carl Peterson <carlopeterson@gmail.com> writes: >> Just thinking out loud here...would it be worth looking into tweaking the >> .htaccess file to do OS-based redirection on the download page, like many >> sites do? That way, if someone requests download.html, they are redirected >> to download-win.html if the server detects Windows, download-mac.html if it >> dectects OS X, download-nix.html for *nix, and so on, with >> download-all.html being the current page (and .htaccess silently >> redirecting here if there is no OS match). This would allow us to put all >> the information on one page for an operating system and recommend or not >> based on what is actually available. > > No, based on what computer is used for downloading. That's more than > often sufficiently different to make this a nuisance. What we could > attempt doing is to move the entry for the purportedly detected > operating system to the top. Fair enough. That said, I'm not sure we can do this without either (1) introducing more redundancy in the individual documentation pages than Graham was concerned about (because then we still have to present the information on each page, just in a different order and layout), or (2) utilizing back-end scripting (PHP, etc.) to custom-serve the content based on the http header. It is interesting that in recent memory, almost every site I go to for downloadable software automatically serves the OS-specific version, including both commercial sites and open-source, etc. projects. Typically it would be something like: <h1>Download LilyPond [version number] for [operating system]</h1> <p>(For other operating systems or versions, <a href="download-all.html">click here</a>)</p> [Present latest stable and dev versions side-by-side, with release notes and licenses linked in] [Insert note about LilyPond being text-based] [Link to OS-specific editing solutions] I'm not saying that this is necessarily the *best* solution, but I think the success rate seems to be high enough to warrant looking at.
Sign in to reply to this message.
On Mon, Dec 16, 2013 at 01:50:53PM -0500, Carl Peterson wrote: > (2) utilizing back-end scripting (PHP, etc.) to custom-serve the > content based on the http header. We're using a donated web-server, and don't have root access. When (not if) PHP has another security hole, I don't think we want us to be responsible for somebody else's server getting hosed. - Graham
Sign in to reply to this message.
On Wed, Dec 18, 2013 at 5:30 AM, Graham Percival <graham@percival-music.ca> wrote: > On Mon, Dec 16, 2013 at 01:50:53PM -0500, Carl Peterson wrote: >> (2) utilizing back-end scripting (PHP, etc.) to custom-serve the >> content based on the http header. > > We're using a donated web-server, and don't have root access. > When (not if) PHP has another security hole, I don't think we want > us to be responsible for somebody else's server getting hosed. > Indeed, I meant this paragraph to indicate two generally undesirable options for serving the content with the detected operating system info on top and all the other information rearranged on the same page, not as "this is what we should do." Carl P.
Sign in to reply to this message.
|
