Re: Poll: Most helpful feature after 1.3?

[Chris Travers <..hidden..>]

On Fri, Jul 22, 2011 at 1:16 PM, Luke <..hidden..> wrote:

> However, the documentation of the time did talk about requiring PostGreSQL
> and a web server, although there was no way provided, that i remember, to
> test for either.  You were just expected to know whether they were there,
> and how to get them if they weren't.

This may not come across right but there is some wisdom in at least
providing a checklist and where  to look for more documentation.  I am
reminded by one of the best pieces of technical writing to come out of
the early 1990's (the early SCO Xenix system administration manual---
the technical writing was way better than the software).

On page 3 it stated, and I kid you not:  "Before you begin, make sure
your computer is properly assembled.  Please make sure you know how to
turn on and off the computer, and how to reset it.  Also make sure you
know how to put floppy disks in the floppy disk drive.  If you are
unsure about any of these steps, please consult your hardware
documentation."

This seems silly to us today, but given the era when computers were
not nearly so common, they provided these instructions even for a
server operating system (albeit a bad one largely developed at the
time by Microsoft).  Just as in that era it made sense to tell
prospective users what sorts of things they were required to know and
tell them where to get the answers, I think the same approach is valid
today.  It's also worth noting that this documentation took the user
from that level up through  questions of system security, inode
management, and other technical areas, and did so in a way which an
average non-technical reader could probably understand without too
much difficulty.

That's a standard worth shooting for.


> For 1.3, it already has been done.  I can not overestimate the value of
> Erik's contributions in putting together a base install file that covers
> the debian side as well as the general cases.  What he doesn't have there
> can be easily plugged in to the final product, and provided we get rid of
> all the extra little READMEs and such that are laying around (I haven't
> looked lately, so maybe we have), to get down to a single source for
> install info, this is already a vast improvement.

I would not say done.  BTW, Erik's contributions here are vast and
extremely helpful.  I don't want to underrate them or underestimate
their value.  I would say that both Erik and I are on the same page
that there is still more that needs to be done on the documentation
side.  We've been discussing this feedback a little bit.
>
>> Wouldn't be even better to have a .deb or .rpm that went like this:
>>
>> 1. you want to run LedgerSMB
>> 2. you do not have Postgres running
>
> but might on another machine.
>
>> 3. you do not have Apahe running
>
> Assuming Apache is your webserver of choice, the .deb should depend on a
> web server in general, yes.
> Checking whether it is actually running, however, is a bit beyond the
> scope.
> The best the dependency checking should do, is make sure that the system
> believes that a web server exists.
>
> The debconf process, however, should ask where the database is going to be
> (I.E. on which machine), as a critical level question.  If you don't give
> it something it can test against, it should probably fail configuration in
> some helpful way, directing you to install a local DBMS if one isn't
> installed.
> Imho, it should *not* do that for you.  There are just too many possible
> configurations.
>
>  > 4. run this script
>> 5. enter passwords as required by the script
>
> Some of that should be done in debconf.

As a note here, debian is beyond my expertise.  It would be
interesting to break that off onto a subthread and see who else
responds and what can be done to ease the installation there.
>
>> 6. start the service
>
> If the web server and/or database manager are not running, there may be a
> good reason for that.  It should probably do a restart on the web server
> if it can, because that is the Debian way, but handling errors that come
> up when it does that, such as an inability to start, are beyond its
> operational parameters.
>
>> 7. enter a password for the superuser and a user for ledgerSMB > 8. run
>>
>> The script my contact wrote did everything to step 6. It was after
>> that that I couldn't get the program to actually run so I could set up
>> my COA etc.
>
> Not that we're really trying to solve that now, but something sounds very
> wrong with this whole situation.  If all of those things were done, and
> all of the PERL modules were installed, and PostGreSQL was configured to
> let you log in (see Chris' messages), you should have been able to do
> those things.
>
>> I didn't respond any sooner because I've heard RTFM lots of times and
>
> For what it's worth, I doubt you would have heard that in this case.  We
> all know that the "m" in this case was not great in covering installation
> issues, so telling you to read it for other than a basic question, would
> not have been helpful.
> Spilled milk, that, but for the future, always at least ask.  Even an RTFM
> tells you something you didn't know for certain before--I.E. that the
> community is either full of people who didn't read your question clearly;
> or that you need to explain your question in more detail so they know you
> did read the manual; or that this is just an unhelpful group this time
> around.  Either way, you know more than you knew before you asked, and can
> act accordingly.

Just as a note, I don't mind asking if people have checked a specific
piece of documentation.  Sometimes you look all over and miss
something.  Also knowing whether a piece of documentation has been
read can be helpful in figuring out what the matter is.

However I will be clear.  If people are dismissive of problems in the
way an RTFM response usually suggests, then that's a separate problem
and we'd need to deal with that.

My $0.02

Best Wishes.
Chris Travers