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

Re: documentation, FAQs et al





On 8/26/07, Peter Houppermans <..hidden..> wrote:
I have come across an Ubuntu guide which, frankly, is spot on re.
requirements.

See http://ubuntuforums.org/showthread.php?t=311029, the only problem is
that I am using Ubuntu 7.04 and thus get rewardded with "Error! No
GlobalDBH Configured or Could not Connect" - AFAIK I've done it all
correct, but I did not that this version of Ubuntu installs Postgresql
8.2 rather than 8.1.


If this error occurs and you have already edited the ledgersmb.conf, you can see the exact cause of the error by:
1)  cd to the LedgerSMB application root directory
2)  run the following command:
perl -MLedgerSMB::Sysconfig -e print

No output means no error.  Usually however, you will get a good and informative error.  Just don't post the password to the email lists ;-)

I will add this procedure to the installation documentation. 

  So if that problem can get fixed I would push it
back into that forum, and I would then suggest to ask permission from
the author to use this as the 'Ubuntu guide'.
That would then also give a structure for an <any other Linux/BSD> guide.


Our current approach is to suppliment the INSTALL and README files with README.[OS/Distro/etc].  This way we can document what is different, what needs to be changed, etc.

The problem with most FAQs is focus.  The fact that a Q is asked "F" may
point at a documentation deficiency.


Agreed.  BTW, we do accept patches to documentation :-)  And plain text is fine as a format.
 

  I would prefer an update to a
install/admin/backup/user guide over the need to scour through a bunch
of FAQs.  IMHO, FAQ content should be in the category 'miscellaneous' -
anything else ought to make its way back into the relevant docs.


A better option, IMO, is to add a FAQ section to each chapter of each manual or at the end of each document.  That way people go into the document, find what they need, look at the FAQ in that chapter, or whatever.

Best Wishes,
Chris Travers