Migration and documents

[David Tangye <..hidden..>]

On Thu, 2007-04-26 at 10:22 +0100, Ed W wrote: 
> However, I don't disagree that in a perfect world we should have a 
> better migration path.  Perhaps someone will step up and help work on 
> the migration scripts - these are never easy to write once a project has 
> diverged far enough.
I am migrating to LSMB currently. Its not straight-forward, unless you
have kept completely up to date by reading all the email list, for the
past several weeks. The documents/info are in many places: about 10
files in the tar, plus the website, plus the email list. Basically this
is already a bloody great mess.

I suggest BTW 3 documents. 3 place to look (actually only 2 for installs
upgrades and migrations)

1. A 'User Guide'. Target = USERS, not developers. Covering accounting,
and how LSMB does it ONLY. Includes only those parts of setup that are
user-controlled, ie via LSMB screens. Does not have a single reference
to words/phrases like 'Tex', 'Latex', 'Perl', 'CGI', 'command line',
'run the following SQL', 'edit this file' etc. (Basically 95% of the
current 'User Manual'?). 
Add in the info on:
 - Contributors
 - License
 - Copyright

2. An 'Administration Guide'. Target = techos, who are needed to install
the support software, and LSMB itself, and do any
configuration/customisation (that might involve words/phrases like those
above).
Suggested chapters:
 - Installation
	- Sourcing the software, package management etc
	- Postgres
	- DBI, DBD-Pg etc
	- Web servers
	- LSMB itself
 - Security (technical backgrounder)
	- Login/access
 - Upgrading
 - Customising
	- templates
	- language
	- extra code
	- (etc)
 - Data backup and recovery
 - Migration from sql-ledger
	BTW: I am looking at this process being best achieved by:
		1. Install LSMB as per normal (version 1.1.12)
		2. (Optional: create play LSMB datasets as required)
		3. (Optional: continue working with sql-ledger (versions 2.6.12 thru
to 2.6.27 - not 2.8.x)), backup SL dataset(s) for migration.
		4. Create LSMB production dataset(s) using psql
		5. Restore SL backup(s) into LSMB production dataset(s)
		6. Run migration script (I am working on this)
		7. (Optional: parallel run sql-ledger and LSMB. Check data (ie reports
and invoices etc) are consistent between them)
		8. Continue with LSMB.
	Any comments? - in a separate thread perhaps?


3. A simple release notes document covering ONLY
 -  a summary of changes, but pointing to the email list and wherever
your bugs reporting/resolution stuff is for full details

 - a reference to the installation instructions in the Administration
Guide'. DONT repeat stuff here - put it into the 'Administration Guide'
under the chapter on Installation.

 - ToDo? If included this needs to point to the bug/enhancement website,
and MIGHT include a CURRENT summary of the high priority items there.


All 3 docs go into the /doc subdirectory.
Other files eg CONTRIBUTORS, README, COPYRIGHT, LICENSE TODO etc go into
one guide or the other.


If you are going to have documents at all, keep them up to date (or
destroy them: Out of date stuff hanging around is just irritating). Get
info out of the email lists and the website and into the above more
quickly. Make sure the documentation is current for each version
release, so the docs are correct for each version of software they are
released with.

Why not master the 2 guides in openoffice, and generate the pdfs from
that? Particularly if chapters were subdocs, any number of people could
submit updates easily, and the docs might stay current and become more
comprehensive. Right now, I suspect hardly anyone knows how to update
the docs at all.

Also, I think someone should tidy up and organise the website better:
its starting to become inconsistent and disorganised already. Why are
only some lefthand 'Navigation Items' repeated as header-links at top
right? Also the faqs seem to be a totally random set of about 5 items.
Each could easily be found in other more logical places. Drop faqs
altogether, or else if anyone can commit the time, at least organise
them and keep them more aligned to what IS frequently asked (ie
presumably on the email list)).

>   I guess that bugs referring to the migration 
> scripts though are the ones that ironically people read most into 
> despite it being a one time bit of pain.
I do not understand what you are trying to say, especially 'read most into'.
(and 'it' = migration not the bugs nor migration scripts: OK I can guess that part)

> With regards to all the other packaging issues people raise, whilst I 
> can see the merits of using your distro's package manager, at the end of 
> the day CPAN is a fantastic package manager in it's own right and the 
> simple solution is just to do "perl -MCPAN -e shell" and run the list of 
> installations that are required that way.  Result is up and running in 
> no time.
Agreed. It seems that the consensus lately is that LSMB is not to be
aimed at user installation, but that a techo will be required, if not to
install it, then at least to customise it. In this case there is no real
need for the software to be packaged into debian, rpm, gentoo (portage?)
etc packages. Techos should be able to handle a tarball and bash & perl
scripts.

OK, back to my installing LSMB.