[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Migration and documents

First, I think that INSTALL and UPGRADE files should always be
maintained.  Those filenames are in upper case not because I am
yelling but because that is the standard convention.  If your install
is a mess, I am guessing you didn't read these files :-)

I do not expect we will ever stop maintaining them, and we will
probably always document a manual install process regardless of
whatever else we offer.

Secondly, this may change over time, but at the moment the manual is
designed to teach people how to use the software.  It is well
structured (I think), the Table of Contents entries link to the
apropriate sections, URL's are clickable, etc.  (Yes, you may notice
there are no visual clues that this is the case, but this was because
it was assumed that the primary format would be *printed.*

The manual is written for people of any level of accounting or
technical background.  It comes with the sources so if people want, it
can be stripped down for specific training sessions, but the idea is
that it is out there to teach the people
installing/maintaining/administering the software how it is supposed
to work.

Third, the release_notes is designed to provide people exactly what
information they need to get up and running quickly.  It includes
changes relating to SQL-Ledger as well as prior versions.

Fourth, I think it is time to say "put your money where your mouth
is."  Most of us on the core team are putting a lot of time into what
we feel are the most important priorities:  security, process control,
and accounting logic.  The fact is that nothing else matters if those
are not handled 100% right.  Other issues may be addressable once
those are really nailed down.  But that won't be likely before we get
close to 2.0.  If you want to radically restructure the documentation,
you are free to make contributions, and these may or may not be
accepted depending on their quality.

Best Wishes,
Chris Travers

On 4/26/07, David Tangye <..hidden..> wrote:


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.


-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Ledger-smb-users mailing list
..hidden..
https://lists.sourceforge.net/lists/listinfo/ledger-smb-users