Re: [GMG-Devel] docs: Debian / rpm-based distros and sudo / root

[ayleph]

On 03/06/2015 09:03 AM, Christopher Allan Webber wrote:
> Jim Campbell writes:
> 
>> As things are now, our docs start out by saying, "If you're on a
>> Debian-based system, do this . . . but if you're on a RPM-based system
>> do that . . . " but those types of distinctions end after the mention of
>> specific python packages (i.e., there are no Fedora/RHEL/CentOS
>> instructions for which postgres packages to install). Based on this,
>> should we include instructions for the Fedora/RHEL/CentOS family in the
>> official docs, or should we focus just on Debian in the official docs?
>> Right now, the instructions are 1/4-baked on the Fedora/RHEL/CentOS
>> side.  
> 
> I think we should support them.

My personal opinion, I'd suggest making the published docs more generic
and putting more specific details that are subject to change (eg, the
exact package to install on a certain distro) on the wiki. In the
published docs, give the basic dependencies and their versions. Link to
a page on the wiki that gives details about specific packages for
specific distributions.

The advantage of keeping the specifics on the wiki is that it can be
updated between releases of the published docs (if a package changes for
a distro), and people who use $OBSCUREDISTRO can add details about their
distro to the wiki as they like.

>> Personally, I would like to include that family of distros as an
>> alternate, but don't want to muck-up the docs. It would be better to
>> have a documentation set that people can follow-along w/o having to
>> constantly "do this" for one platform or "do that" for another platform
>> [0].  For now, I think it would be better to provide top-notch
>> instructions for Debian, though. What do folks think?  This would mean
>> removing the notes about RPM-based distros in the start, and moving
>> those docs elsewhere. If folks would like to include Fedora/RHEL/CentOS
>> in the official docs, I could add-in my Fedora/RHEL/CentOS stuff.  I’m
>> not sure if it’s ready, though.
> 
> What do other projects do?  I wonder sometimes why things seem so much
> harder for our docs than for other projects... maybe it's just because
> end-user web applications are rare and all of them would be this hard
> for ours, but maybe there is something clearer we could do better.

We do some stuff other webapps don't. `./configure && make` is an oddity
for a webapp, for sure. Using multiple package managers is an oddity.
Not bundling extlibs is an oddity.

Most of the other webapps I've installed have been from tarballs with
everything included. The docs give general instructions on dependencies
and configuration, but you end up figuring out a lot on your own. Lots
of them don't bother telling the end user about setting up user/group
accounts, permissions, working directories, etc. because their target
audience is someone who's used to doing this kind of stuff as an admin.

When installing a new webapp, I generally go through a lot of pain
trying to set it up. If I get it right, I might document it on a wiki or
blog post. The process is usually something like this:

Download package. Extract. Configure. Attempt to run. Check log for
failure. Install undocumented missing package x. Attempt to run. Check
log for failure. Search interwebs for error y. Find a fix or workaround.
Take notes. Nuke the install, which at this point is a complete mess.
Create sensible user, group, and data directories. Reinstall the app
following previous notes.

And yes, this is the process I've gone through (numerous times) with
MediaGoblin as well. I should compare my notes against the deployment
instructions and see if I can offer anything. But the fact is,
MediaGoblin with all of its dependencies is a lot more complicated than
most webapps I've used.

>> Also, there are alternate instructions for sudo and root. I’d like to
>> eliminate the root-based instructions, and just feature use of sudo
>> where appropriate.  (I was actually the one who did things this way . .
>> . in going through it, I don’t think it works well, though  : ).  If
>> anyone prefers to use root, they could certainly sort out the
>> differences and remove the “sudo” command as they go through things. 

+1

-- 
ayleph