Open Stack

I think we can all agree that lowering the barrier to entry for potential
contributors serves as one of the larger reasons for migrating from DocBook
to Sphinx/RST. In addition to a rather complex build environment and rigid
syntax, one could argue that the addition of custom semantic markup
specific to our documentation made DocBook even more daunting for potential
contributors. During the migration to Sphinx/RST, we somehow added semantic
markup (e.g., :file:`file.conf`) that clouds an otherwise simple language
already familiar to a significant number of potential contributors,
particularly developers who we really need to keep our documentation fresh
and useful. Furthermore, our semantic markup doesn't render any differently
than standard Sphinx/RST (e.g., :file:`file.conf` vs. ``file.conf``). I
propose that we eliminate our semantic markup and follow Sphinx/RST
standards/conventions as much as possible.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150925/ead288bb/attachment.html>