Re: [check] install guide (draft)

Thanks all (sorry for the bulk reply) for your suggestions to the new
install guide. I basically implemented most if not all of them, with 
one minor point of disagreement and a few open questions.

You are of course welcome to follow-up...


Dom wrote: 
> Looks really good! I would make two pages out of it

Yes, I gave it a try and that's indeed better.
 
> Minor details follow:
> - for the versions of the Perl modules, unless the dependencies are
> stronger than I think, I suggest that the versions should be indicated
> as minimal versions (e.g. CGI (>= 2.81) )

Done automagically by following Ville's suggestion and linking to
/source instead of the prerequisites part of /docs/devel.

> - a few <acronym> or <abbr> on the abbreviation could help contributors
> getting into the project (FPI, SGML, ...)

Will take care of that when polishing the text, i.e. when I'm happy with
the bulk.

> - move out the "Thanks" from the body of the text to an acknowledgment
> section

yes

> - the development download from CVS could be removed from the generic
> install guide, and moved in the separate contrib document

In the version I have now, there are only two small notes about CVS,
which should not be too misleading for people installing for the
tarballs. I don't really want to "copy" the whole guide for developers
using CVS and this seems like a decent compromise (reserving my right to
change my mind without justification later... ;)

> - a link to a tutorial on using the CPAN installer could be useful

yes

> - "Copy [validatorpath]/httpd/conf/httpd.conf to
> [validatorpath]/httpd/conf/validator-httpd.conf" is strange; why do we
> incite using a different filename than the one used in our
> repository/tarball?

There are two config files that will always be modified when installing.
One is the validator'S config, which we copy to /etc/w3c/, and the other
is the Web server's, which I suggest to copy to another location too.
This makes upgrading and error recovery safer.

Should I explain this in the guide?

> - the configure section (but part 6) is really Apache-centric
> (configuration files, includes, restarting on change of config, etc.); I
> would suggest making it clearer and removing the 'with apache' prefixes

yes

> - s/webserver/Web server/
> - s/online/on-line/
> - s/mailinglist/mailing list/ (and a link to the archives would be a
> good idea too)

Um did someone fix these spelling errors or did I do it in my sleep?
Thanks anyway!

Karl wrote:
>1 in fact three pages.
>        An intro doc with:
>                You are a developper
>                You want to install the validator.

Well, the intro doc is more or less what the /docs/ index page is
supposed to do, but I guess it may be improved, too...

> - We should try to find three people who have the competences to create
> clickorama installer. I have recently installed Bloxsom (Perl) on my
> macintosh. You download a package, you double click and it's working...
> it's very very elegant. If we can do that for the validator, it will
> help a lot.

Yes, clickorama installers are a good help. That may not be very easy in 
our case because of the fact that :
- this is server software, so we should not expect people to have a
  GUI... even less a consistent cross-platform one (though I suppose a
gnome installer would be cool, but a luxury given our resources)
- dependencies and prerequisites are what make the installation
  difficult.
- we do have something close to "clickorama" with the deb and rpms done
  by Ville and Frederic.

Ideas:
- a small shell/perl script copying files where needed (and asking
  questions along the way) and pre-editing the conf files.
- a dummy CPAN module taking care of the dependencies. We can't bundle
  the validator in a CPAN module (or can we? Ville, you're our local
expert, do you have any idea?) but we can pretend...


> - Have you thought already about localization of install docs and to
> maintain the different versions?

Localization should not be too much of a problem. For the versions, I
believe we just need to have the documentation fit the latest tarball
version. Or am I missing the point?

Ville Wrote:

> An up to date list of dependencies and the older installation
> instructions is at http://validator.w3.org:8001/source/
> Combining that and the new guide would be a good idea in order to remove
> redundancy and improve the chances that the information will be kept up
> to date.

Indeed. I moved the reference to prerequisites to this place. I'm
considering simply removing the prereq part of the devel documentation
when I work on it (i.e probably tomorrow)



Thanks again, looking at the result I think your suggestions are
starting to make the guide shine!

-- 
olivier

Received on Thursday, 25 December 2003 04:46:17 UTC