modify our docs in preparation for restructuring

[martenson]

and start moving admin content from old wiki

We have to design the structure for Administration docs. I was thinking about making one section for each of

• Production Galaxy (ping @natefoo)
• Dependencies (ping @mvdbeek)
• Admin UI
• Special topics (GIE, telescope, webhooks, chat...). ping @erasche

Other ideas?

This is how it looks now with this PR:

[dannon]

I still think it's a bad idea to pull admin docs out and put them in the code docs. Admins aren't necessarily developers, and this separation is a step backwards from what we were making a big push towards in having a single channel for all documentation and communication (the hub).

I proposed on IRC that, if we must ship admin documentation with galaxy, then we should copy the tree from hub, which would be the authoritative source, at release time. (not unlike how we include and update galaxy-lib, etc.)

[hexylena]

I see it less as "moving admin docs with code docs" which sounds weird, and more as "shipping the deployment instructions with the product rather than requiring admins to access a separate website for config and making sure they choose the docs for their version". So this is my viewpoint.

Still strongly in favour of including admin docs as there is often release specific information that changes with time. IMO it is best to make sure that admins can easily access docs relevant to them and their specific deployment. (Especially if they manage multiple galaxies at different versions)

No opinion on if it is transcluded from hub. I worry that if people make admin related changes, that they might forget to document them in the separate hub repository. This concern may be unfounded.

[dannon]

@erasche I'd say that "shipping the deployment instructions with the product" is dying, though, with 'apt-get install galaxy' anyway. Maybe I'm weird, but I don't look for the postgresql documentation that shipped with the packages. I don't even know if it exists. I almost exclusively end up at postgresql.org or stackoverflow.

(that said, transclusion seems to be what's acceptable for most people, and I think that's probably the path forward)

[natefoo]

Hey, I actually got started on this, haven't committed it yet, though. I was thinking there should be a top-level "Administration Documentation" (Admin? Administrator?), with subsections for production installs on various linuxes (with distro-specific commands e.g. apt-get install nginx-full etc.). Then there'd be a separate section for in-depth documentation of production topics such as cluster integration, etc.

I think GIE ought to be first-class and we should be making every effort to support it out of the box. It's really not hard to get it working, and it'll be trivial w/ uWSGI, which is ready to ship today.

[natefoo]

Also I'm with @erasche on the doc location question. Even if they're with the code, they'll still be hosted. I think having the admin guide along side the other guides in the docs is a good thing, and having the docs in the code encourages contributors to keep the admin docs up to date as features are added. Plus, it allows for version-specific documentation. Although we only build the dev branch right now on docs.galaxyproject.org, it's structured such that we can build other branches. Just like the PostgreSQL docs, this will allow admins to choose their deployment version and get the correct docs for that version (and allow for contributors to update and correct docs for a specific version even once newer versions are released).

[hexylena]

Oh. Apparently I made a comment as a "review" rather than as a one-off comment. Oh bother. Just now noticed that my comment was still sitting here.

[hexylena]

change underline length