[gluster-devel] Documentation Tooling Review

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



The Red Hat Gluster Storage documentation team and I had a conversation about how we can our upstream documentation more consistent and improved for our users, and they're willing to work with us to find where the major gaps are in our documentation. This is awesome! But it's going to take some work on our side to make this a reality.

One piece that's come up is that we should probably look towards changing current tooling for this. It turns out that our ReadTheDocs instance search is failing because we're using markdown, and this is a known issue. It doesn't look like it's going to be fixed anytime soon. 

Rather than continue to try to make RTD serve our needs, I'd like to propose the following changes to where our documentation lives and in what language: 
I'd much rather pattern after docs.openshift.org, move to ASCIIdoc and use ASCIIbinder as our engine to power this. What that does is give us control over our overall infrastructure underneath our documentation, maintain our existing git workflow for adding to documentation, and matches with other communities that we work closely with. I'm mindful that there's a burden of migration again, but we'll be able to resolve a lot of the challenges we have with documentation currently: more control over layout, ability to change the structure to make it more user friendly, use our own search however we see fit. 

I'm happy to take comments on this proposal. Over the next week, I'll be reviewing the level of effort it would take to migrate to ASCIIdocs and ASCIIbinder, with the goal being to have this in place by end of September. 

Thoughts?
- amye 

--
Amye Scavarda | amye@xxxxxxxxxx | Gluster Community Lead
_______________________________________________
Gluster-devel mailing list
Gluster-devel@xxxxxxxxxxx
http://www.gluster.org/mailman/listinfo/gluster-devel

[Index of Archives]     [Gluster Users]     [Ceph Users]     [Linux ARM Kernel]     [Linux ARM]     [Linux Omap]     [Fedora ARM]     [IETF Annouce]     [Security]     [Bugtraq]     [Linux]     [Linux OMAP]     [Linux MIPS]     [eCos]     [Asterisk Internet PBX]     [Linux API]

  Powered by Linux