> 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
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
On Tue, Mar 17, 2015 at 3:30 AM, Shaun McCance <shaunm at redhat.com> wrote:> 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.I think with porting of content, main focus should be on new content. If we create the complete documentation procedure i.e. automating this long procedure ----> writing content in markup language -> pull request -> discussion -> changes -> Identify the module and upstream -> converting content in relevant design, style -> pushing to upstream -> updating CentOS docs -> update website. If this toolchain becomes friendly, I am sure even the normal CentOS user, if learns new thing, would happy to write a document about it and push it to us. Even upstream software benefit with this documentation .> > 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 aHence this thread comes into existence on this mailing list to discuss the workflow and tools with those people who actually deal with this on frequently basis. This was my attempt to start discussion on technical aspect of this. http://lists.centos.org/pipermail/centos-docs/2015-March/005594.html> 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.I agree. But as Jason said we need to experiment, give people this new option.