Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

modify our docs in preparation for restructuring #3738

Merged
merged 5 commits into from Mar 15, 2017

Conversation

Projects
None yet
6 participants
@martenson
Copy link
Member

commented Mar 10, 2017

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:
screenshot 2017-03-10 12 08 59

modify our docs in preparation for restructuring
start moving admin content from old wiki
@dannon

This comment has been minimized.

Copy link
Member

commented Mar 10, 2017

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.)

@erasche

This comment has been minimized.

Copy link
Member

commented Mar 10, 2017

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

This comment has been minimized.

Copy link
Member

commented Mar 10, 2017

@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

This comment has been minimized.

Copy link
Member

commented Mar 11, 2017

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

This comment has been minimized.

Copy link
Member

commented Mar 11, 2017

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).

@martenson martenson changed the title [WIP] modify our docs in preparation for restructuring modify our docs in preparation for restructuring Mar 14, 2017

@galaxybot galaxybot added this to the 17.05 milestone Mar 14, 2017

@jmchilton jmchilton merged commit 27cb4fb into galaxyproject:dev Mar 15, 2017

2 of 5 checks passed

api test Test started.
Details
continuous-integration/travis-ci/pr The Travis CI build is in progress
Details
framework test Test started.
Details
integration test Build finished. 25 tests run, 0 skipped, 0 failed.
Details
toolshed test Build finished. 580 tests run, 0 skipped, 0 failed.
Details
@erasche
Copy link
Member

left a comment

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.

@@ -1,4 +1,4 @@
Developer Documentation
Development Documentation
=======================

This comment has been minimized.

Copy link
@erasche

erasche Mar 15, 2017

Member

change underline length

@martenson martenson deleted the martenson:admin-docs-from-hub branch Mar 16, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.