Re: Helping with the documentation
Hi Graham,just a short note from FISL, where I just saw a session on documentation. Wouldn't it be cool to have excercises for each section? Easy ones makes the learning targets of each part of the manual more explicit, and difficult ones make the manual more interesting for sophisticated users. Ciao!2006/4/14, Graham Percival [EMAIL PROTECTED]: For information about proposing changes to the docs, seehttp://lilypond.org/web/devel/participating/documentation-adding ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Fwd: Helping with the documentation
Am 2006-04-22 um 16:03 schrieb Han-Wen Nienhuys: Wouldn't it be cool to have excercises for each section? Easy ones makes the learning targets of each part of the manual more explicit, and difficult ones make the manual more interesting for sophisticated users. Maybe there are some people who would appreciate such; I myself hate books etc. where you are supposed to answer questions and do exercises - I want to solve my own problems, not go to school. But that are only my 2 ct. Greetlings from Lake Constance --- fiëé visuëlle Henning Hraban Ramm http://www.fiee.net http://angerweit.tikon.ch/lieder/ http://www.cacert.org (I'm an assurer) ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: Helping with the documentation
On 4/22/06, Han-Wen Nienhuys [EMAIL PROTECTED] wrote: Hi Graham, just a short note from FISL, where I just saw a session on documentation. Wouldn't it be cool to have excercises for each section? Easy ones makes the learning targets of each part of the manual more explicit, and difficult ones make the manual more interesting for sophisticated users. I think it's more important to finish and improve the documentation than to add exercises. David ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: Helping with the documentation
On 22-Apr-06, at 7:03 AM, Han-Wen Nienhuys wrote: Wouldn't it be cool to have excercises for each section? Umm. I'm not really looking for more cool things to add to the docs, you know. :)Cool things should happen once the basic stuff is done. Easy ones makes the learning targets of each part of the manual more explicit, and difficult ones make the manual more interesting for sophisticated users. Sorry, I agree with Fiëé and David. I obviously didn't see the presentation you did, but my initial reaction is that exercises are useful teaching tools for people who don't want to learn the material. Teenagers don't see the use of trigonometry, so math textbooks include questions. But the only reason people read the LilyPond manual is because they have a specific goal in mind -- the readers already have their own exercises in mind. We already have vague learning targets: the division of the manual sections into chapter (instrument-specific notation) and section (vocal music). Once I've finished everything else on my list, it might be interesting to add half a dozen questions in their own section, kind-of like a how to use this manual document -- although we already have one of those. But I really doubt that adding exercises to every section would be worth the effort. Cheers, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: Helping with the documentation
Quoting Bart Kummel [EMAIL PROTECTED]: One of the reasons that earlier wiki's weren't a big success could be that people do not want another place to look for documentation. Therefore the best solution (in my opinion) is to replace the current docs with a wiki. I think the way the documentation is done now is a little bit oldfashioned. It may be good for the linux-geeks amongst the lilypond users. But for Windows users, who generally have less knowledge about operating systems, it is now not easy to use and/or to contribute. Actually, one of the earlier wiki's was actually integrated into the manual, so you could click at a button at the bottom of each page in the on-line manual in order to add or read comments, suggestions for updates and so on. Still, the number of contributions was extremely small. Actually, I would say that the number of people who have contributed constructively to the documentation over the last months is much larger than we ever had earlier and as long as Graham thinks the editing task is managable, we shouldn't complain. /Mats ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: Helping with the documentation
On 15-Apr-06, at 5:41 PM, David Feuer wrote: On 4/15/06, Graham Percival [EMAIL PROTECTED] wrote: Just to completely clarify, my comment about making a tarball available was aimed at people working on the docs, but who are not comfortable compiling the docs from CVS. I think it'd be great to make a tarball available that's almost compiled, but not quite. That is, it has everything complete but instead of PNGs has Postscript fragments, and a makefile to run them all through Ghostscript. In fact... since LilyPond comes with GhostScript, why not distribute the docs as a self-extracting executable that does this? Err... this is probably possible. Although we might also need texinfo, and ImageMagick, and... well, why not simply give people access to CVS? If you have the right versions of software installed, it's easy to compile the docs. That's how I do it -- I don't build lilypond myself; I use GUB. If you're curious about how this works, I could post instructions. I'm not certain what problem this is trying to solve, though. Cheers, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: Helping with the documentation
Hi all,Unfortunately I do not agree with most of your points. About searching: I often use google. With the option site:lilypond.org you can narrow the search to that site and by including a version number in the search terms you can narrow it down to one version. This method could be used with a wiki too. About the tarballs. Most Windows users don't even know what a tarball is. Personally I hate local documentation. I always have a browser window open, so it's very easy to seach for a topic by using Google as explained above. And Graham: I don't get your point saying that the current docs are easier to maintain that a wiki. In the current setup, every piece of documentation has to go through your hands. With a wiki, everyone could add things themselves, so you will get far less work, even if you think editing a wiki is more comples than what you are doing now. (Apart from the fact that in my opinion there is nothing simpler than editing a wiki page...) Making tarballs available with newer docs than the website looks like a good step, but I think a website should always represent the latest state. One of the reasons that earlier wiki's weren't a big success could be that people do not want another place to look for documentation. Therefore the best solution (in my opinion) is to replace the current docs with a wiki. I think the way the documentation is done now is a little bit oldfashioned. It may be good for the linux-geeks amongst the lilypond users. But for Windows users, who generally have less knowledge about operating systems, it is now not easy to use and/or to contribute. Let me end with this: I do appreciate all the work you do in making both lilypond itself and its documentation better with every release. You're all doing a great job! Thanks for that! Best regards,Bart Kummel, Hilversum, The NetherlandsOn 4/14/06, Graham Percival [EMAIL PROTECTED] wrote:On 14-Apr-06, at 8:20 AM, Bart Kummel wrote: So I was thinking of a method to make contibuting to the docs more easy. Perhaps it's a good idea to set up a wiki for the docs.As other people have pointed out, we've tried wikis in the past.Thelatest version is still online: http://wikihost.org/wikis/lilypond/In addition, adding new material to the docs is EASIER than using awiki. I think there are many benefits for using a wiki instead of the way the documentation is done now. I think it's more easy for the editor, because he doesn't have to add all contibutions manually,This is absolutely NO problem for me if I get an email which proposesthe exact changes.The problem in writing docs is in coming up withthe initial text, not in the technical step of translating it into texinfo. Another benefit is that we don't have to wait until a new version of Lilypond is built for new documentation to come available on-line.If this is a serious concern, I could start making doc tarballs available -- or even hosting temporary docs on my webpage.I agreethat sometimes this has bothered me.A third benefit is that the documentation does not depend on one or a few persons any more. There is nothing intrinsic in a wiki that does this.Whether thedocumentation depends on a few people is simply a matter of thecommunity.As I've said, adding new material to the docs is easierthan adding an entry to a wiki.All you need is email. Cheers,- Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: Helping with the documentation
Unfortunately I do not agree with most of your points. About searching: I often use google. With the option site:lilypond.org you can narrow the search to that site and by including a version number in the search terms you can narrow it down to one version. This method could be used with a wiki too. I think you're missing at least part of my point. I know how to use Google with a targeted search. The problem is that the amount of text surrounding a match that Google returns is often insufficient to determine if it's what I want, whereas scanning through the whole manual in a browser automatically returns an entire page of context (if I want it). Personally I hate local documentation. Many people don't have reliable broadband always available. You have told us about your personal preferences, which is entirely legitimate. But my personal preferences are that I really, really don't like using wiki-only documentation. Geoff ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: Helping with the documentation
I think you're missing at least part of my point. I know how to useGoogle with a targeted search. The problem is that the amount of text surrounding a match that Google returns is often insufficient todetermine if it's what I want, whereas scanning through the wholemanual in a browser automatically returns an entire page of context(if I want it). OK, Got the point now. Personally I hate local documentation. Many people don't have reliable broadband always available.You have told us about your personal preferences, which is entirelylegitimate. But my personal preferences are that I really, reallydon't like using wiki-only documentation. This discussion is not only about personal taste. It's about the fact that a large part of the people who maintain lilypond and its documentation are people who are very familiar with computers, linux, et cetera. I'm trying to act as a devil's advocate here: there are lots of people out there using Windows, having not much computer knowledge, who are potential users of and contributors to lilypond + docs. I think we're missing those people here, because we do things in a linux-like way. Using a wiki is just one suggestion to change this. Perhaps there are other ways. I'd like to hear other people's ideas about this.Best regards,Bart Kummel ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: Helping with the documentation
Hello, all -- I'd like to hear other people's ideas about this. I almost exclusively use the (local) PDF docs as my first target -- full text searches are easy and complete. Next (i.e., if I don't find the answer there), I use the lilypond.org docs -- usually by this point, I know precisely where the answer will (should) be. Third, I search the list archives -- often, if the docs don't have the answer, someone else has run into the same problem before. Lastly (i.e., if too much time has passed and I still don't have the answer), I search using Google -- in general, I find all such searches to be so algorithmically general that they are less helpful than the above methods in finding a very specific answer quickly. Best regards, Kieren. ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: Helping with the documentation
About the tarballs. Most Windows users don't even know what a tarball is. This is a good point. I think zip files are much more portable than tarballs. Geoff ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: Helping with the documentation
Bart Kummel [EMAIL PROTECTED] writes: About the tarballs. Most Windows users don't even know what a tarball is. no problem, a zip file can also be generated. anyway, AFAIK all major unzip programs for windows extract tarballs and other formats as well. In the current setup, every piece of documentation has to go through your hands. and that's a good thing to maintain quality and accuracy. if using a wiki he had to go every page to make sure the information is good and current. IMHO it's a mistake to assume that editorial control is not needed in a wiki. in fact, I found editorial control much harder in wiki-like environments. One of the reasons that earlier wiki's weren't a big success could be that people do not want another place to look for documentation. Therefore the best solution (in my opinion) is to replace the current docs with a wiki. well, I don't have a saying on this, but since there were already 2 unsuccessful wiks in the past I doubt Graham, Jan, or Han-Wen will set it up. Why don´t you set one up as a proof of concept and show how it can be better then the current setup? I think the way the documentation is done now is a little bit oldfashioned. maybe, but this old-fashioned setup can generate html, pdf, and info; has a decent revision control (most wikis have only very basics control version features). another point is that it is concurrent, many people can work on it at the same time. There is not a wiki that allows that. and because wikis are centralized, if the main server is down one can not work on it. not to mention that the wiki format is a *mess*, heve you tried to convert a complex doc from one wiki to annother? the texinfo format may be old-fashioned, but it's stable and well supported. Regards, Pedro Kroger ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: Helping with the documentation
Well, maybe a compromise would be to use something like haloscan. It allows comments in the page. users could point things in the documentation that aren't clear, etc. pedro ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: Helping with the documentation
no problem, a zip file can also be generated. anyway, AFAIK all major unzip programs for windows extract tarballs and other formats as well. WinXP has native support for reading zip files but not for tarballs. Geoff ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: Helping with the documentation
Geoff Horton [EMAIL PROTECTED] writes: no problem, a zip file can also be generated. anyway, AFAIK all major unzip programs for windows extract tarballs and other formats as well. WinXP has native support for reading zip files but not for tarballs. this is not much of a problem because a zip file is as easy to generate as a tarball. but just for the record, if windows users want to be able to extract files in tarballs and other formats as well they can use the free program 7-zip: http://www.7-zip.org/ pedro ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: Helping with the documentation
this is not much of a problem because a zip file is as easy to generate as a tarball. but just for the record, if windows users want to be able to extract files in tarballs and other formats as well they can use the free program 7-zip: http://www.7-zip.org/ I know. I use it. But is Joe Average who just wants to get some music set going to have it? Perhaps if the choice is to stick with tarballs, a link should be placed on the page to the 7-zip site (or some other appropriate site). But I am rather opposed (not that I have any say in the matter) to making people download extra programs, no matter how useful. Geoff ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: Helping with the documentation
- Original Message - From: Pedro Kröger [EMAIL PROTECTED] To: [EMAIL PROTECTED] Cc: lilypond-user Mailinglist lilypond-user@gnu.org Sent: Saturday, April 15, 2006 11:26 AM Subject: Re: Helping with the documentation Bart Kummel [EMAIL PROTECTED] writes: About the tarballs. Most Windows users don't even know what a tarball is. Pedro replied: no problem, a zip file can also be generated. anyway, AFAIK all major unzip programs for windows extract tarballs and other formats as well. Well, some zip programs cannot open bz2 files. But, the documentation tarball is already so big, that only compressing in the zip format would make it too big, don't you think? In the current setup, every piece of documentation has to go through your hands. Pedro reploed: and that's a good thing to maintain quality and accuracy. if using a wiki he had to go every page to make sure the information is good and current. IMHO it's a mistake to assume that editorial control is not needed in a wiki. in fact, I found editorial control much harder in wiki-like environments. I very much agree with that too. Bart wrote: Another benefit is that we don't have to wait until a new version of Lilypond is built for new documentation to come available on-line. Graham replied If this is a serious concern, I could start making doc tarballs available -- or even hosting temporary docs on my webpage. I agree that sometimes this has bothered me. It would be nice if somewhere in the documentation page there would be informations like this: Latest revisions: April 2, 2006 Section 2.6 April 1, 2006 Section 3.2 This way people that don't use broadband internet could check on updates and wouldn't be downloading over 14Mb of docs every so often. These revisions could point directly to the on-line manual or also be a link to a temporary documentation at Graham's webpage. Now, another remark about the documentation page: The PDF for Regression Tests and Tips and Tricks have the same name: collated-files.pdf. It would be good to have different names for each. Regards, Eduardo Vieira ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: Helping with the documentation
Hi all, My first post, sorry if I haven't lurked long enough to learn any posting protocols. If it matters, I'm an OS X user... [quote] One of the reasons that earlier wiki's weren't a big success could be that people do not want another place to look for documentation. Therefore the best solution (in my opinion) is to replace the current docs with a wiki. I think the way the documentation is done now is a little bit oldfashioned. [/quote] What about people like me who write music on a computer that is NOT attached to the Internet? I personally like a two-pronged approach - I prefer core documentation (the reference manual) to be in the form of a local pdf file that I can either view or print as needed. I think that core documentation should be a mirror of what is available on the web site, with each document assigned a revision number and a date, preferably matching major software revisions. The second prong of my approach would be to have some kind of less formal web-based information (the user guide?) with tips and tricks, FAQs, and/or lessons... Doug ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: Helping with the documentation
On 15-Apr-06, at 5:12 AM, Bart Kummel wrote: And Graham: I don't get your point saying that the current docs are easier to maintain that a wiki. In the current setup, every piece of documentation has to go through your hands. That is not the problem. The problem is that very few people send me documentation to go through my hands. :) Making tarballs available with newer docs than the website looks like a good step, but I think a website should always represent the latest state. Sorry, I was unclear. I was talking about the current unusual situation, wherein Han-Wen is away for two weeks and we have no releases. - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: Helping with the documentation
On 15-Apr-06, at 7:39 AM, Geoff Horton wrote: this is not much of a problem because a zip file is as easy to generate as a tarball. but just for the record, if windows users want to be able to extract files in tarballs and other formats as well they can use the free program 7-zip: I know. I use it. But is Joe Average who just wants to get some music set going to have it? Perhaps if the choice is to stick with tarballs, a link should be placed on the page to the 7-zip site (or some other appropriate site). But I am rather opposed (not that I have any say in the matter) to making people download extra programs, no matter how useful. Woah, this got out of hand. :) Just to completely clarify, my comment about making a tarball available was aimed at people working on the docs, but who are not comfortable compiling the docs from CVS. I think there are three people in this category, and if this would be useful for them, I'll supply it in whatever format they want. These are not intended for normal users. - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: Helping with the documentation
On 15-Apr-06, at 2:50 PM, Eduardo Vieira wrote: Graham replied If this is a serious concern, I could start making doc tarballs available -- or even hosting temporary docs on my webpage. I agree that sometimes this has bothered me. It would be nice if somewhere in the documentation page there would be informations like this: Latest revisions: April 2, 2006 Section 2.6 April 1, 2006 Section 3.2 It might be somewhat nice, but I really can't see this being worth the trouble. This way people that don't use broadband internet could check on updates and wouldn't be downloading over 14Mb of docs every so often. Well, once we get the docs looking good, we won't need to change them all that often. :) Now, another remark about the documentation page: The PDF for Regression Tests and Tips and Tricks have the same name: collated-files.pdf. It would be good to have different names for each. Hmm, good point. My long-term plan is to do something different with the regression files, though, so I'll leave them `as is' for now. Cheers, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: Helping with the documentation
On 4/15/06, Graham Percival [EMAIL PROTECTED] wrote: Just to completely clarify, my comment about making a tarball available was aimed at people working on the docs, but who are not comfortable compiling the docs from CVS. I think it'd be great to make a tarball available that's almost compiled, but not quite. That is, it has everything complete but instead of PNGs has Postscript fragments, and a makefile to run them all through Ghostscript. In fact... since LilyPond comes with GhostScript, why not distribute the docs as a self-extracting executable that does this? David ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Helping with the documentation
Hi all, I'm getting a bit overwhelmed working on the documentation, so I'm asking for help. I've posted a list of tasks to the -devel mailist. Some of them require very little previous knowledge of LilyPond, and are actually a great way to learn. You can read them here: http://lists.gnu.org/archive/html/lilypond-devel/2006-04/msg00231.html Apart from those tasks, I have on more request: please don't forward an email from -user to -devel or the bug mailist with the message you should improve the docs in this area. If you think an email contains important information or clarification of the documentation, please take the time to propose *exact* changes to the documentation. If you are personally involved in the discussion, then you probably know more about this area than I do. This is certainly true if the issue involves anything that is covered in Chapter 7 Instrument-specific notation. Finally, some background about me: I'm just a normal user. In August 2004, I volunteered to become Documentation Editor, because I speak English as a first language and have some time to contribute. I didn't program LilyPond, nor do I have any special training in music publication. I play cello and viola at a high level (as a university undergraduate performer); my knowledge about printed music comes from reading music. I have seen a lot of string music, and some orchestral scores, but I have very little knowledge of vocal music, piano, guitar, and the like. If you play any of those instruments -- anything which is in Chapter 7 -- then I practically guarantee that you know more about using LilyPond to create music for those instruments. For information about proposing changes to the docs, see http://lilypond.org/web/devel/participating/documentation-adding Thanks, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: Helping with the documentation
Hi Graham,What I'm missing currently in the docs is a section about organ music. There are some instrument-specific things that can be discussed in such a section. I'm willing to help with that, but I have very little spare time. So I was thinking of a method to make contibuting to the docs more easy. Perhaps it's a good idea to set up a wiki for the docs. I believe there is a lilypond plugin for wikis, to make it easy to post comments and their results. We could start by only adding some new topics and then gradually move more and more topics from the old docs to the wiki. After some time we end up with the full documentation in a wiki. Since wikis have a versioning system built in, we could use that to keep info for older versions of Lily available. I think there are many benefits for using a wiki instead of the way the documentation is done now. I think it's more easy for the editor, because he doesn't have to add all contibutions manually, he only has to edit them. Another benefit is that we don't have to wait until a new version of Lilypond is built for new documentation to come available on-line. A third benefit is that the documentation does not depend on one or a few persons any more. I hope you want to consider my suggestions. As I said, I don't have much time, but I'm willing to help in the few moments I have. I have some experience with setting up a wiki. And for the documentation itself: I play the organ as an amateur, so I know a low about organ and also choral music notation. Best regards,Bart Kummel, Hilversum, The NetherlandsOn 4/14/06, Graham Percival [EMAIL PROTECTED] wrote:Hi all,I'm getting a bit overwhelmed working on the documentation, so I'm asking for help.I've posted a list of tasks to the -devel mailist.Some of them require very little previous knowledge of LilyPond, andare actually a great way to learn.You can read them here: http://lists.gnu.org/archive/html/lilypond-devel/2006-04/msg00231.htmlApart from those tasks, I have on more request: please don't forward anemail from -user to -devel or the bug mailist with the message you should improve the docs in this area.If you think an email containsimportant information or clarification of the documentation, pleasetake the time to propose *exact* changes to the documentation.If you are personally involved in the discussion, then you probably know moreabout this area than I do.This is certainly true if the issueinvolves anything that is covered in Chapter 7 Instrument-specificnotation. Finally, some background about me: I'm just a normal user.In August2004, I volunteered to become Documentation Editor, because I speakEnglish as a first language and have some time to contribute.I didn't program LilyPond, nor do I have any special training in musicpublication.I play cello and viola at a high level (as a universityundergraduate performer); my knowledge about printed music comes fromreading music.I have seen a lot of string music, and some orchestral scores, but I have very little knowledge of vocal music, piano, guitar,and the like.If you play any of those instruments -- anything whichis in Chapter 7 -- then I practically guarantee that you know more about using LilyPond to create music for those instruments.For information about proposing changes to the docs, seehttp://lilypond.org/web/devel/participating/documentation-adding Thanks,- Graham___lilypond-user mailing listlilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: Helping with the documentation
So I was thinking of a method to make contibuting to the docs more easy. Perhaps it's a good idea to set up a wiki for the docs. I'm of two minds about this. The advantages you point out are real, but I also encounter a lot of frustration with wiki-based docs; for one thing, there's no very good way to make a quick scan through them looking for something. That makes answers are even harder to find if your mind doesn't work the same way as that of the person who wrote the section in question, or if the answer to your question is covered in a place completely different from where you expect it to be. I often find answers just by loading the full-page version of the docs (off my hard drive, so it's quick), doing a text search for a string, and looking at the material around hits to see if it looks like I'm in the right place. Most search engines don't return enough context for this to work well. Geoff ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: Helping with the documentation
On 4/14/06 9:45 AM, Geoff Horton [EMAIL PROTECTED] wrote: So I was thinking of a method to make contibuting to the docs more easy. Perhaps it's a good idea to set up a wiki for the docs. I'm of two minds about this. The advantages you point out are real, but I also encounter a lot of frustration with wiki-based docs; for one thing, there's no very good way to make a quick scan through them looking for something. That makes answers are even harder to find if your mind doesn't work the same way as that of the person who wrote the section in question, or if the answer to your question is covered in a place completely different from where you expect it to be. I often find answers just by loading the full-page version of the docs (off my hard drive, so it's quick), doing a text search for a string, and looking at the material around hits to see if it looks like I'm in the right place. Most search engines don't return enough context for this to work well. Geoff I agree. I have found the most useful way for me to work with Lilypond is to download the documentation tarball and have this installed on my hard drive. I can then easily travel through the User Manual and the Program Reference sections. I would find using a Wiki cumbersome. By the way I would like to thank those who make the Documentation tarball available. This was a big move forward for me as the previous documentation did not include the images or they did not get installed on Mac OS X. This meant that I had to go to the internet and farm the required pages from the Lilypond site. I am sure the tarball is a far better solution. Thanks very much! Walter Hofmeister ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: Helping with the documentation
Bart Kummel [EMAIL PROTECTED] writes: So I was thinking of a method to make contibuting to the docs more easy. Perhaps it's a good idea to set up a wiki for the docs. this was done in the past without success. a wiki would be an advantage (besides it's shortcomings) if there was a good number of people wiling to maintain it, but that doesn't seem to be the case. the current docs are in much better shape now than ever, and the format in use allows to generate html pages and pdf as well. if one wants to help, the easiest way is to write in plain text and send it to Graham, he will take care of the necessary conversion to the format in use (texinfo). Pedro ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: Helping with the documentation
On 14-Apr-06, at 8:20 AM, Bart Kummel wrote: So I was thinking of a method to make contibuting to the docs more easy. Perhaps it's a good idea to set up a wiki for the docs. As other people have pointed out, we've tried wikis in the past. The latest version is still online: http://wikihost.org/wikis/lilypond/ In addition, adding new material to the docs is EASIER than using a wiki. I think there are many benefits for using a wiki instead of the way the documentation is done now. I think it's more easy for the editor, because he doesn't have to add all contibutions manually, This is absolutely NO problem for me if I get an email which proposes the exact changes. The problem in writing docs is in coming up with the initial text, not in the technical step of translating it into texinfo. Another benefit is that we don't have to wait until a new version of Lilypond is built for new documentation to come available on-line. If this is a serious concern, I could start making doc tarballs available -- or even hosting temporary docs on my webpage. I agree that sometimes this has bothered me. A third benefit is that the documentation does not depend on one or a few persons any more. There is nothing intrinsic in a wiki that does this. Whether the documentation depends on a few people is simply a matter of the community. As I've said, adding new material to the docs is easier than adding an entry to a wiki. All you need is email. Cheers, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
