[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: new website (general info)
From: |
John Mandereau |
Subject: |
Re: new website (general info) |
Date: |
Wed, 10 Jun 2009 16:22:31 +0200 |
User-agent: |
Thunderbird 2.0.0.21 (X11/20090320) |
Graham Percival a écrit :
Hmm. I guess we could rename AU to "General Information" or
something like that?
What would be the form of that "General Information"? A manual or a
website? Renaming AU to something
else implies keeping a manual form, doesn't it? Even if you heavily
customize HTML output, the source would
still be written in Texinfo, a documentation-oriented language that
doesn't fit a web site design. Oh well, you
can insert as many @html blocks as you like, but doing this for the
whole website seems overkill to me; this
will not bring any better web design more easily than plain HTML plus
the existing Python formatting scripts
(format-page.py and Co). Then, Texinfo would be only useful for parts of
the web site that would be of any
use in PDF format. I second Han-Wen about the importance of making a
clear distinction between different
information forms: documentation, general website... they are not read
the same way, by the same people,
nor within the same timescales.
This new doc would include:
(in no particular order)
- crash course
IMHO there's no use having it in printable form: printed output would be
useful to take long time read it, which is not the purpose of this
document, unlike the tutorial.
- alternate editors (in particular jedit and the like)
- OS-specific setup
- command-line options
This is already in AU, I mean, this is a manual of the documentation
and is meant to be there, not on the general website IMHO.
- mailists, how to report bugs, info about LSR
This belongs to the general website. You need to have an Internet
connection and a web browser
(and an email client if you like) to report a bug, so I don't see any
benefit in making them available
in printed format.
- lilypond-book and convert-ly
If you mean documentation of these programs in a form of a manual, then
let's just keep them in a manual.
- FAQ
It could be interesting to have the FAQ in PDF, but I'd rather have it
as a standalone PDF. Texinfo
could be used to generate a plain HTML file like we have in web branch
sources.
- essay
The introduction of the manuals already contains one avatar of the essay
in Texinfo,
so this will be even more natural than the FAQ to have it in Texinfo on
the website.
- comparsions (if we do them)
- press/publications
- testimonials
All these belong to the website, not to a manual.
- acknowledgements + dedication
- examples
There may be a reason for not having the acknowloedgements in the docs,
but I
wouldn't be hurt by having them in the documentation.
... mao. That's 90% of the material on the website. I mean, it
only leaves the main page, features, download links, and the
"current help wanted" pages.
Although I like the idea of making some contents of the website
available in PDF by writing them
in separate Texinfo documents, I guess trying to include them in a
single big Texinfo doc would bring
nothing of much use in PDF output (I can easily imagine somebody who'd
like to print a particular
document, but printing the whole content of the website seems a bit
crazy, unlike printing a complete
manual; navigating a site on-screen in PDF format seems weird too),
while making it unnecessarily
complicated and painful to format HTML output with a combination of
texi2html init file/CSS/Python
script postprocessing, to make it look like a website and not a manual.
I hope we'll get to a consensus based on more than just human resources
constraints.
Best,
John