[Koha-devel] Lets improve the Koha installation documentation

[Mark Tompsett]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/koha-devel/attachments/20120824/06ef2d3b/attachment.htm>