[CentOS-docs] Docs strategy and tactics [RFC]

Mon Mar 16 22:00:11 UTC 2015
Shaun McCance <shaunm at redhat.com>

On Tue, 2015-03-17 at 01:54 +0530, kunaal jain wrote:
> > On Mon, Mar 16, 2015 at 10:48 PM, Shaun McCance <shaunm at redhat.com> wrote:
> > I like putting focus on this. It provides people a resource for things
> > they actually want to do. Nobody wants just an operating system. I also
> > think it's a great avenue for getting community contributions. It's easy
> > to make a one-time contribution on a topic you know well without digging
> > into how it affects everything.
> >
> > An anecdote: I pay Linode for a VPS. I run a few things on there that
> > I'm only barely qualified to run. The Linode docs have some of the best
> > guides I've seen for things like setting up Postfix and Mailman to run a
> > mailing list. It's not docs for Linode per se, but it is docs for what
> > you actually want to do once you've paid for that shiny VPS.
> >
> > I think there's a lot of potential here for CentOS to be the source for
> > setup guides and the like for stuff people actually do once they've
> > installed an enterprise OS.
> 
> This is one of the main motivation about this. Curating content from
> contributors which write about how to do things on CentOS. When I get
> a new shiny OS, I need to know how powerful it is, what I can do with
> it.
> I have a VPS on digitalocean. The reason I got convinced of using a
> VPS was their documentation. How awesome a VPS is, what I can do with
> it. Their docs is selling their product!

Just to throw another wrench in: I don't know what DigitalOcean's docs
are like, but Linode generally provides their guides for Ubuntu, Debian,
and CentOS. However, for whatever reason, they tend to do Ubuntu first.
So there are bunches of guides without CentOS versions.

They do allow people outside Linode to submit guides. So outside of
normal CentOS docs, a useful exercise would be for people to port
non-CentOS guides on Linode (and other places) to CentOS. It would
increase mindshare for CentOS.

> > It sounds like you want to set up content pools that multiple projects
> > and upstreams can pull from. That's a very hard problem, and even harder
> > if you need to support multiple formats. The technical details of such a
> > system could easily take up another email thread.
> 
> That's the goal. Start a new project on this. A new toolchain. It will
> take time to develop it fully. There is interest of me taking this as
> Google Summer of Code Project with Karsten as mentor.

Sure. I've dealt with quite a bit of this while working on GNOME docs.
It's challenging, but mostly enjoyably so. I mentioned to Karsten
off-list that, if you want a usable system at the end, it's important to
really define the workflow and what tools are needed. I've had quite a
few GSoC projects that just ended up as interesting experiments, but
never got used. Interesting experiments can be fine, but not if your
documentation strategy depends on them.

--
Shaun