Rework the documentation around our cloud services

[choldgraf]

After a recent conversation with @colliand and the CS&S folks, this is a re-working of the "pilot documentation" to prepare for an "alpha" launch of the hub service. It does the following major things:

• Uses the PyData Sphinx Theme so that we have more consistent style / structure with our 2i2c.org website
• Splits this documentation into two major sections: one for hub Administrators, and one about the service itself.
• Adds more meta-information about the cloud services in general, a overview matrix of features, and pages for each of the two major hub distributions that we offer.
• Adds a bit more build infrastructure to make it easier to build the docs locally.

Here's a quick GIF of the header of this site compared with 2i2c.org, along with the changes also proposed in 2i2c-org/2i2c-org.github.io#69

In addition to this, I'd also like to make the following URL changes:

• Make docs.2i2c.org point to this site
  • The Hub Administrator guide would then be available at docs.2i2c.org/admin
  • The "About our Service" guide would be available at docs.2i2c.org/about
• Make devops.2i2c.org point to our current pilot-hubs documentation

part of https://github.com/2i2c-org/meta/issues/78

[colliand]

I like the changes! I added a few comments while reviewing. I don't think we are in final form but see these as a significant improvement. I suggest we merge and continue our work together.

[choldgraf]

I made another update after a recent conversation with @colliand. It took inspiration from the Strip documentation, which has been pointed out as a good example to follow. It makes the following changes:

• Re-works this site to be more of a high level documentation that points to other places. I imagine we can host this at docs.2i2c.org.
• Updates the logo to be further in-line with 2i2c.
• Includes links to our Hub Engineer's guide (which I'm calling the DevOps Guide since I suspect that will be more descriptive than Hub Engineer) as well as our Team Compass

The reasoning for adding the last two links is that (as @colliand insightfully put it to me), part of 2i2c's mission is to provide transparency into how it operates, and how others might follow our path. As such, our "internal" documents like pilot-hubs and team-compass can still provide a lot of value to outside stakeholders, and help us emerge as a leader in open and inclusive organizations, so we should encourage that others look at them.

would love feedback - particularly from @colliand if he thinks this is a step in the right direction. If so, and if nobody from the tech team objects, I suggest we merge this and iterate from there.

[choldgraf]

OK I think this is more-or-less ready to go. There's still a lot more to improve, but this is I think a good step. I'll leave it open for a day or two to see if others have ideas (or objections 🙂)

[sgibson91]

I really like this! Feels clean and easy to navigate

[choldgraf]

thanks @sgibson91 and @colliand for taking a look@!

[damianavila]

Late to the party but I really like this one 😉 .