Re: [atomic-devel] Doc format?

[Nick Coghlan <ncoghlan gmail com>]

On 9 March 2016 at 01:47, Matt Micene <nzwulfin 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   |   ncoghlan gmail com   |   Brisbane, Australia