Greetings,
Right now. People are probably doing “less INSTALL.blah”. Less is standard.
We’ve got a perl application being installed, so perldoc isn’t a far fetched
expectation. As long as we get a format where people can easily “<program>
<install file>” after a “sudo apt-get install <program>”, I don’t care.
Particularly if there is a README.1ST file, or just a base INSTALL file, that
tells people how to read the INSTALL files. But this begs the question: are we
creating a meta-problem?
Additionally, the notion of converting the documents to a Wiki page makes me
wonder if perhaps we have forgotten to ask the reason for having the install
files. Is the INSTALL.blah file supposed to be there as an offline version of
the Wiki? Perhaps, it is supposed to complement, but not replace? Right now,
the current instructions that Tomas Cohen and I have worked on for Ubuntu do
refer back to the Wiki page, because frankly, “just tell them to do these
commands without explaining it” makes the instructions shorter. The Wiki is
flushed out and explains parts a little more. I’d really like to flush it out
more, but writing and testing good documentation is time consuming and I have
other projects to work on.
So, I’m not so keen on the convert it back to a wiki page. It also creates the
problem of information overload. People skim it, think they have read and
understood it, but they really have not. People want to install quickly and
without hassle. Reading and following something that is a long step by step
guide can be tiring, boring, and prone to error. We already have people making
installation mistakes. Documentation is supposed to reduce that. So, shorter
install files, and longer wikis make some sense to me.
I pondered versioning the instructions for OS releases, but decided against
that, since the instructions should overlap significantly between OS releases.
I even started a re-attempt of Koha 3.4 on Ubuntu 8.04, but gave up as I would
have to CPAN the roughly 18 modules missing. I briefly considered 3.6 and 3.8,
but Perl 5.10 and Modern::Perl were a big enough stumbling block for a “new to
linux” person that I figured documenting how to tweak your perl version is
beyond the scope of a “normal” install. Should we split only by OS version?
Well, there was a lot in there, so I better summarize/clarify (in no particular
order):
- Why do we include an installation instructions in the form of INSTALL.{OS}
currently?
- Is INSTALL.{OS} meant to be a replacement or complement to the Wiki version?
- Should INSTALL.{OS} be longer, the same (identical), or shorter than the Wiki
version?
- Should INSTALL.{OS} be something other than plain text? How will people know
how to read it?
- Is INSTALL.{OS} sufficient for documentation purposes? Why not
INSTALL.tarball, INSTALL.git, INSTALL.packages (which reflect the three types
of install)? Why not a mix (e.g. INSTALL.tarball.{OS})?
I’m just brainstorming a little. A good program needs good documentation. And I
hope to help improve it.
GPML,
Mark Tompsett_______________________________________________
Koha-devel mailing list
[email protected]
http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel
website : http://www.koha-community.org/
git : http://git.koha-community.org/
bugs : http://bugs.koha-community.org/
