Feedback request | Documentation site reorg, switch to Markdown

[Peter Matulis]

On Fri, Mar 3, 2017 at 11:19 AM, Robert Young <robert.e.young at gmail.com>
wrote:

> Hi Simon,
>
> I agree with your assessment. Standard markdown lack some of the
> features that make technical writing easy to read, however, there are
> several extensions to markdown that make it better. Although I really
> like DO's extension, I'm not sure it is a free spec. I know for sure
> that it is not a common spec. On the other hand, Pandoc
> (http://pandoc.org) is a wonderful tool that you can get from the
> standard repos. It has extensions for syntax highlighting, inline html,
> and, most importantly, can convert text from markdown (and dozens of
> other formats) to DocBook and vice versa. I think even if we leave
> DocBook as the official markup choice, Pandoc can be referred to as a
> way for contributors to use the tools they feel most comfortable with,
> but still contribute. I would have to do some testing on the fidelity of
> the format output to what the existing documentation looks like. If this
> is of interest, let me know, and I will start running some tests.
>
>
I'm well aware of pandoc. It's what I used a few years back when I tried to
get the Server Guide converted to RST. It is also the tool that we use in
Canonical to convert stuff. It never converts perfectly. There is always
collateral damage that requires fiddling with. Elsewhere in this thread a
similar idea was proposed: users write in their preferred format and
conversion happens afterwards by a Doc committer. If it's the writer
instead then they are free to do what they want with their time.

I'd also like to mention that in Canonical we do extend the standard GitHub
Markdown.

Peter