Re: [GMG-Devel] devel Digest, Vol 45, Issue 7

[chris]

Just make separate pages for each set of instructions. Debian, Arch,
Fedora/RHEL/CentOS.

I'm thinking:
https://mediagoblin.readthedocs.org/en/stable/siteadmin/deploying/yourdistro.html

Move Debian instructions to the Debian page, clean them up a bit and get
rid of the non-Debian parts. Put up construction signs on the other
instruction pages while they're being worked on.

The extention idea sounds cool, but why use JS when you could just make
a freakin' directory?

Just my 2cents.

address@hidden:
> Send devel mailing list submissions to
>       address@hidden
> 
> To subscribe or unsubscribe via the World Wide Web, visit
>       http://lists.mediagoblin.org/listinfo/devel
> or, via email, send a message with subject or body 'help' to
>       address@hidden
> 
> You can reach the person managing the list at
>       address@hidden
> 
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of devel digest..."
> 
> 
> Today's Topics:
> 
>    1. Re: docs: Debian / rpm-based distros and sudo / root
>       (Christopher Allan Webber)
>    2. Re: docs: Debian / rpm-based distros and sudo / root (ayleph)
>    3. Re: 0.8.0 freeze! (Jim Campbell)
>    4. Re: 0.8.0 freeze! (Christopher Allan Webber)
>    5. Re: docs: Debian / rpm-based distros and sudo / root
>       (Christopher Allan Webber)
>    6. Re: Gitorious aquired by Gitlab (Tiberiu-Cezar Tehnoetic)
> 
> 
> ----------------------------------------------------------------------
> 
> Message: 1
> Date: Fri, 06 Mar 2015 11:03:11 -0600
> From: Christopher Allan Webber <address@hidden>
> To: address@hidden
> Cc: address@hidden
> Subject: Re: [GMG-Devel] docs: Debian / rpm-based distros and sudo /
>       root
> Message-ID: <address@hidden>
> Content-Type: text/plain; charset=utf-8
> 
> Jim Campbell writes:
> 
>> Hi All,
> 
> Hi Jim!
> 
>> 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.
> 
>> 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.
> 
> ... So, one crazy idea I've had is to set up some custom sphinx
> extension for distro/OS specific instructions, maybe looking like
> 
> .----------------------------------------------.
> | V Debian (Ubuntu/Trisquel/Gnewsense)         |
> |----------------------------------------------|
> |   sudo apt-get install monkeys               |
> |==============================================|
> | > Fedora (RedHat/CentOS/Foo)                 |
> |==============================================|
> | > OS X                                       |
> '----------------------------------------------'
> 
> (see http://pamrel.lu/3cacf/ if not using fixed width fonts)
> 
> The idea is once you expand the section for your setup, it expands the
> rest.
> 
> Not sure how hard this would be to implement.  You can add special
> syntax/forms to Sphinx, so I think not too hard from the Sphinx side,
> but it would also require adding JS.  Not sure how it would affect the
> texinfo generation, either.
> 
> Maybe not worth the time but I thought I'd throw it out there...
> 
>> 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. 
> 
> I don't have a strong preference.
> 
>> Jim
>>
>> [0] The OpenStack docs are transitioning fully from DocBook to
>> Python-Sphinx, and they're working on this problem in Python-Sphinx. The
>> conditional-related Sphinx features don?t quite do what they want, and
>> they?re working on a sphinx extension to allow advanced, conditional
>> builds of docs. With the stuff they?re working on, they would have a
>> single rST/python-sphinx source document, but could build out the html
>> instructions for Ubuntu using one build command, and build out the html
>> instructions for Fedora/RHEL/CentOS using another build command.  I
>> think this would be nice to have for MediaGoblin in a later release.  
> 
> Ah okay!  So actually that kind of sounds like what we want.  Maybe we
> should work with them?
> 
> 
> ------------------------------
> 
> Message: 2
> Date: Fri, 06 Mar 2015 09:49:11 -0800
> From: ayleph <address@hidden>
> To: Christopher Allan Webber <address@hidden>,
>       address@hidden
> Cc: address@hidden
> Subject: Re: [GMG-Devel] docs: Debian / rpm-based distros and sudo /
>       root
> Message-ID: <address@hidden>
> Content-Type: text/plain; charset=utf-8
> 
> 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
>

signature.asc
Description: OpenPGP digital signature