Re: Helping with the documentation

[Bart Kummel]

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 Netherlands

On 4/14/06, Graham Percival <address@hidden > 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.  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