Re: Web: Download: Add introductory text (issue 40510046)
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 ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
On Mon, Dec 16, 2013 at 01:27:05PM +0100, David Kastrup wrote:
Maybe interactive is a useful term? Like
LilyPond is not an interactive program: its sole task is translating
a textual description of music into typeset music. For creating that
textual description, an editor is required.
While any general-purpose text editor can be used for this task, some
applications are specifically tailored to working with LilyPond.
Yes, this is getting verbose again, but it's likely hard to whittle it
down significantly. At any rate, it might be a starting point regarding
the concepts and information we need to convey.
Three sentences is sufficently succinct, IMO. I have no problem
with a patch that changed the download warning macro into this.
(although the above would need to be reworded slightly to
accommodate the @refs{})
- Graham
___
lilypond-devel mailing list
lilypond-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
Am 18.12.2013 11:33, schrieb Graham Percival:
On Mon, Dec 16, 2013 at 01:27:05PM +0100, David Kastrup wrote:
Maybe interactive is a useful term? Like
LilyPond is not an interactive program: its sole task is translating
a textual description of music into typeset music. For creating that
textual description, an editor is required.
While any general-purpose text editor can be used for this task, some
applications are specifically tailored to working with LilyPond.
Yes, this is getting verbose again, but it's likely hard to whittle it
down significantly. At any rate, it might be a starting point regarding
the concepts and information we need to convey.
Three sentences is sufficently succinct, IMO. I have no problem
with a patch that changed the download warning macro into this.
(although the above would need to be reworded slightly to
accommodate the @refs{})
- Graham
I suggest to wait with this too until it is clear which pages are
finally there to @ref to
Urs
___
lilypond-devel mailing list
lilypond-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
On Wed, Dec 18, 2013 at 5:30 AM, Graham Percival gra...@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. ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
Am 16.12.2013 04:31, schrieb Graham Percival: On Mon, Dec 16, 2013 at 11:29:44AM +0800, Graham Percival wrote: Urs Liska u...@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 ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
Carl Peterson carlopeter...@gmail.com writes: On Dec 16, 2013 12:16 AM, Graham Percival gra...@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 ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
Am 16.12.2013 10:25, schrieb David Kastrup: 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. +1 What we could attempt doing is to move the entry for the purportedly detected operating system to the top. Or provide a direct link for that OS but keep the full list of entries below. Urs ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
Am 15.12.2013 19:48, schrieb David Kastrup: Urs Liska u...@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 ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
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 ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
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
Re: Web: Download: Add introductory text (issue 40510046)
Am 16.12.2013 07:46, schrieb Paul Morris: Graham Percival-3 wrote 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 Continuing in this direction... what if the list of available editors was then put on the download page itself, just below the LilyPond download content? With a header to the effect of Download an Editor to Use with LilyPond, and a brief explanatory text (these are 3rd party... etc.) with links to the text input pages. Or even more radically, on the download page the list of editors could be in the right-hand column, and the LilyPond download content in the left hand column. Either way this would really convey that you need LilyPond and (probably also) an editor. But would Download still be true as the page title/menu entry? Maybe one could change that to Get LilyPond? Graham Percival-3 wrote My rule of thumb is that doubling the text results in half the number of people reading it. +1 for keeping the website text concise Maybe that's all true. But from my experience LilyPond speech is at times concise to an extent that makes it uncomprehendible for many readers. Urs ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
Am 16.12.2013 07:53, schrieb David Kastrup: Paul Morris p...@paulwmorris.com writes: Here's how I would reword the warning to make it as concrete and simple as possible: Note: With LilyPond you write and edit music by typing text with your keyboard, not by dragging notes around with a mouse. It's not just simple, but wrong. The point is exactly that you _don't_ do this with LilyPond, but that you need a different application for that. Before downloading, please read about LilyPond's Text input. Still won't prepare me that LilyPond has no means to write and edit music. As compared with the current: Note: LilyPond is a text-based music engraver; it is more similar to a programming language than a graphical score editing program. Before downloading LilyPond, please read about our Text input. Which is not helping much. It prepares me for an IDE like Visual C++ or, uh, Frescobaldi. Not for a command line application. Based on my patch: LilyPond is a **command line application** and does not constitute a working environment. Apart from LilyPond itself you'll need a suitable editor. ... ? Urs ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
Urs Liska u...@openlilylib.org writes: Based on my patch: LilyPond is a **command line application** and does not constitute a working environment. Apart from LilyPond itself you'll need a suitable editor. ... The problem I'm running into is that I see a conflict between being accurate and writing in terms that our average user is able to understand. Application already applies a user interface. ed is a commandline application. Guile's commandline interpreter is a commandline application. gcc and LilyPond aren't in the strictest sense of the word: they are batch utilities or programs. They are not interactive. But of course the people we are trying to address here never ever heard of batch processing. And probably never saw those standard cardboxes with a batch of punchcards (and/or a mouse litter) in them. Maybe interactive is a useful term? Like LilyPond is not an interactive program: its sole task is translating a textual description of music into typeset music. For creating that textual description, an editor is required. While any general-purpose text editor can be used for this task, some applications are specifically tailored to working with LilyPond. Yes, this is getting verbose again, but it's likely hard to whittle it down significantly. At any rate, it might be a starting point regarding the concepts and information we need to convey. -- David Kastrup ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
On Mon, Dec 16, 2013 at 4:25 AM, David Kastrup d...@gnu.org wrote: Carl Peterson carlopeter...@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: h1Download LilyPond [version number] for [operating system]/h1 p(For other operating systems or versions, a href=download-all.htmlclick 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. ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
Am 15.12.2013 06:47, schrieb Graham Percival: On Sat, Dec 14, 2013 at 09:46:54AM +, lilyli...@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
Re: Web: Download: Add introductory text (issue 40510046)
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 ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
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 ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
Urs Liska u...@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
Re: Web: Download: Add introductory text (issue 40510046)
On Sun, Dec 15, 2013 at 07:48:28PM +0100, David Kastrup wrote: Urs Liska u...@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 ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
On Mon, Dec 16, 2013 at 11:29:44AM +0800, Graham Percival wrote: Urs Liska u...@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 ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
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 ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
On Dec 16, 2013 12:16 AM, Graham Percival gra...@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. ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
Graham Percival-3 wrote 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 Continuing in this direction... what if the list of available editors was then put on the download page itself, just below the LilyPond download content? With a header to the effect of Download an Editor to Use with LilyPond, and a brief explanatory text (these are 3rd party... etc.) with links to the text input pages. Or even more radically, on the download page the list of editors could be in the right-hand column, and the LilyPond download content in the left hand column. Either way this would really convey that you need LilyPond and (probably also) an editor. Graham Percival-3 wrote My rule of thumb is that doubling the text results in half the number of people reading it. +1 for keeping the website text concise Graham Percival-3 wrote 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. Here's how I would reword the warning to make it as concrete and simple as possible: Note: With LilyPond you write and edit music by typing text with your keyboard, not by dragging notes around with a mouse. Before downloading, please read about LilyPond's Text input. As compared with the current: Note: LilyPond is a text-based music engraver; it is more similar to a programming language than a graphical score editing program. Before downloading LilyPond, please read about our Text input. -Paul -- View this message in context: http://lilypond.1069038.n5.nabble.com/Web-Download-Add-introductory-text-issue-40510046-tp155657p155923.html Sent from the Dev mailing list archive at Nabble.com. ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
Paul Morris p...@paulwmorris.com writes: Here's how I would reword the warning to make it as concrete and simple as possible: Note: With LilyPond you write and edit music by typing text with your keyboard, not by dragging notes around with a mouse. It's not just simple, but wrong. The point is exactly that you _don't_ do this with LilyPond, but that you need a different application for that. Before downloading, please read about LilyPond's Text input. Still won't prepare me that LilyPond has no means to write and edit music. As compared with the current: Note: LilyPond is a text-based music engraver; it is more similar to a programming language than a graphical score editing program. Before downloading LilyPond, please read about our Text input. Which is not helping much. It prepares me for an IDE like Visual C++ or, uh, Frescobaldi. Not for a command line application. -- David Kastrup ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
On Mon, Dec 16, 2013 at 07:53:38AM +0100, David Kastrup wrote: Note: LilyPond is a text-based music engraver; it is more similar to a programming language than a graphical score editing program. Before downloading LilyPond, please read about our Text input. Which is not helping much. It prepares me for an IDE like Visual C++ or, uh, Frescobaldi. Not for a command line application. But surely programming language means edit with vim, compile with make. ;) Cheers, - Graham ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
David Kastrup wrote Paul Morris lt; paul@ gt; writes: Here's how I would reword the warning to make it as concrete and simple as possible: Note: With LilyPond you write and edit music by typing text with your keyboard, not by dragging notes around with a mouse. It's not just simple, but wrong. The point is exactly that you _don't_ do this with LilyPond, but that you need a different application for that. Hi David, Ok, yes, I agree that it's important to convey the need for a separate editor application. I was intending With LilyPond... in the broader sense of overall user experience compared with the typical user's GUI expectations. To me that seems like the first thing to get across. Maybe something like Using LilyPond involves writing and editing music by typing... is clearer and meets the requisite standards for accuracy? Of course, if there's a way to concisely and clearly convey both the overall text-editing user experience and the need for a separate editor that would be even better. -Paul -- View this message in context: http://lilypond.1069038.n5.nabble.com/Web-Download-Add-introductory-text-issue-40510046-tp155657p155928.html Sent from the Dev mailing list archive at Nabble.com. ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
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 ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
https://codereview.appspot.com/40510046/diff/40001/Documentation/web/download.itexi
File Documentation/web/download.itexi (left):
https://codereview.appspot.com/40510046/diff/40001/Documentation/web/download.itexi#oldcode35
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.itexi
File Documentation/web/download.itexi (right):
https://codereview.appspot.com/40510046/diff/40001/Documentation/web/download.itexi#newcode42
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.
https://codereview.appspot.com/40510046/
___
lilypond-devel mailing list
lilypond-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
On Sat, Dec 14, 2013 at 09:46:54AM +, lilyli...@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 ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
Incorporated most of the comments.
Will upload new patch set in a minute
https://codereview.appspot.com/40510046/diff/20001/Documentation/web/download.itexi
File Documentation/web/download.itexi (right):
https://codereview.appspot.com/40510046/diff/20001/Documentation/web/download.itexi#newcode38
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.itexi#newcode40
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.itexi#newcode42
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.itexi#newcode50
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.itexi#newcode53
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.itexi#newcode55
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.itexi#newcode64
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.
https://codereview.appspot.com/40510046/
___
lilypond-devel mailing list
lilypond-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
https://codereview.appspot.com/40510046/diff/40001/Documentation/web/download.itexi
File Documentation/web/download.itexi (left):
https://codereview.appspot.com/40510046/diff/40001/Documentation/web/download.itexi#oldcode35
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.itexi
File Documentation/web/download.itexi (right):
https://codereview.appspot.com/40510046/diff/40001/Documentation/web/download.itexi#newcode42
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.
https://codereview.appspot.com/40510046/
___
lilypond-devel mailing list
lilypond-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Web: Download: Add introductory text (issue 40510046)
Reviewers: ,
Description:
Web: 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.
Please review this at https://codereview.appspot.com/40510046/
Affected files (+31, -2 lines):
M Documentation/web/download.itexi
Index: Documentation/web/download.itexi
diff --git a/Documentation/web/download.itexi
b/Documentation/web/download.itexi
index
91bd1a334ca98a8b106c7cffdbe0dbcd1d7c0d92..46eebd9f850867872f0e7ef06b3a21d68d3d5cd1
100644
--- a/Documentation/web/download.itexi
+++ b/Documentation/web/download.itexi
@@ -32,12 +32,41 @@ our @ref{Text input}.}
@heading Downloads for LilyPond @versionStable
@end ifset
-@warningTextBased
-
@divEnd
@divClass{link-headings}
+@divClass{column-center-top}
+@subheading Before you proceed ...
+
+... you should be aware of some facts and concepts.
+
+LilyPond is a @strong{command line application} translating files written
in
+LilyPond's music description language into graphical
+scores. It does @strong{not} constitute a working environment. What you
will be
+working with for entering your scores is either a @emph{text editor} of
your
+choice, or a dedicated editing tool for LilyPond files.
+
+If you want you can go to @ref{Text input} and learn more about LilyPond's
+input language concept.
+
+@subsubheading I'm new to LilyPond and don't have a dedicated editor yet
+
+If you don't already have an editing environment for LilyPond you should
+go to @ref{Editing} now. Apart from getting information on the editing
+concept you'll find a list of known editors. For beginners it is
+recommended to download and install either @strong{Frescobaldi} or
+@strong{Denemo}. Both can take care of installing LilyPond for you.
+
+@subsubheading I'm already a LilyPond user and just want a new version
+
+However, if you already have and editing environment and simply want
+to install a new LilyPond version you can proceed below.
+
+
+@divEnd
+
+
@divClass{column-left-top}
@subheading For users
___
lilypond-devel mailing list
lilypond-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
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.itexi#newcode57 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.itexi#newcode63 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.itexi#newcode64 Documentation/web/download.itexi:64: to install a new LilyPond version you can proceed below. proceed as described below. https://codereview.appspot.com/40510046/ ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Web: Download: Add introductory text (issue 40510046)
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.itexi
File Documentation/web/download.itexi (right):
https://codereview.appspot.com/40510046/diff/20001/Documentation/web/download.itexi#newcode38
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.itexi#newcode40
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.itexi#newcode42
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.itexi#newcode50
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.itexi#newcode53
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.itexi#newcode55
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.itexi#newcode57
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.itexi#newcode59
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.itexi#newcode64
Documentation/web/download.itexi:64: to install a new LilyPond version
you can proceed as described below.
Is this section even needed?
https://codereview.appspot.com/40510046/
___
lilypond-devel mailing list
lilypond-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-devel
