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

Mon Mar 16 20:24:42 UTC 2015
kunaal jain <kunaalus at gmail.com>

> 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!

>
> One of the reasons this might be the case is that the doc deals with
> integration, so there are multiple upstreams involved. And I think
> that's an area where CentOS docs can provide real value, and drive
> traffic to CentOS. I want a Google search for "How to deploy X with Y"
> to give a CentOS result.
>

In my initial discussion with Karsten, we discussed about this. Right
now if I have to setup or deploy X on Y, I google it, I find lots of
content but they are scattered over the internet. We try them, not
knowing whether they'll work perfectly or not. The new approach
changes this. There will be curated content on one central place.


> For editing, the GitHub workflow is nice in that it allows me to use my
> preferred editor and other tools, but also allows super-easy editing on
> the web. Prose.io is a nice idea, but I haven't found it very compelling
> in practice.
>
> You need tools for maintenance of very large sets of docs. For smaller
> sets, you can deal with a lot more person work.
>
> 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.


My knowledge is very limited, so pardon me if sounds stupid.

Regards,
Kunaal Jain