On 9 March 2016 at 01:47, Matt Micene <nzwul...@gmail.com> wrote: > [Pulling in an off-list discusion] > > Pete, > >> Some things I'd envision from an upstream/Fedora/downstream writing >> collaboration around atomic include: >> - Publicly developed code and supporting documentation, with clear >> contribution >> guidelines. >> - A pool of upstream SMEs available for technical conversations with >> community >> writers. >> - A maintained feature roadmap from upstream >> - SME guidance from upstream on the Fedora Release Notes, so newly landed >> features are documented as they are shipped. > > > I think this sounds like a great idea to get official documentation > collaboration moving again. > > Joe, > >> Since it stalled, is there any chance we can move it towards either >> ASCIIdoc or Markdown and not have a third format in contention? > > > It sounds like we can if only because there's tooling issues with all of the > various markups. What's the least amount of friction to getting new docs > written? AsciiDoc?
I think AsciiDoc is a good way to go, as the main advantage of AsciiDoc is that the underlying semantic model is taken from DocbookXML, so you can plug into any downstream publication toolchain that supports that (especially relevant for Red Hatters, since the publican toolchain consumes DocbookXML). This is especially appropriate if you're wanting to get technical writers involved, as the AsciiDoc/DocbookXML combination is likely to be more appealing to them than the alternatives. By contrast, Markdown's "semantic" model is just HTML, so it's actually a presentation markup language rather than a semantic one, and you need another layer on top of it to give it greater structure (such as using pandoc to jam it into DocbookXML anyway), and flat out can't do things like construct a proper glossary or index. Where Sphinx/reStructuredText is most powerful is in documenting software APIs, especially for low overhead documentation that is autogenerated from the Python docstrings, but there unfortunately aren't any DocbookXML converters that are aware of the semantically significant Sphinx roles - the extant converters all operate at the reStructuredText presentation layer, and hence lose a lot of information :( Cheers, Nick. -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia
