Feedback request | Documentation site reorg, switch to Markdown

[Doug Smythies]

Hi Robert, Simon,

Both very useful e-mails thanks.

Robert: for unknown reasons (it is not in the held queue)
your e-mails do not get to the docs e-mail list (or the
translators one, I think), so this reply is also to get it there.
Note: e-mails from some others are not getting to all copied lists
either. (See rt.ubuntu.com #29630).

That site you referenced, http://pandoc.org seems like it might
be a useful tool. I do not know the differences between "Markdown"
and "GitHub Flavored Markdown", so don't know if it'll work
on what Peter is proposing. I'll leave it to Peter to reply if
he wants you do some testing or not.

On 2017.03.03 08:20 Robert Young 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.
>
> Robert
>
> On Fri, Mar 03, 2017 at 12:43:11PM +0200, Simos Xenitellis wrote:
>> On Fri, Feb 24, 2017 at 2:22 PM, Chris Perry <clissold345 at googlemail.com> wrote:
>>> Hi Peter
>>>
>> ...
>>>
>>> You used the term PITA (pain in the arse, I think). I (kind of) agree
>>> with what you said about server guide xml being a PITA. All markup
>>> languages are (kind of) a PITA. The problem I have with your proposal
>>> is that (as far as I can see) you're moving from one PITA (server
>>> guide xml) to another PITA (Markdown).
>>>
>> 
>> Digitalocean are using Markdown for their online tutorials.
>> 
>> Compared to the standard markdown
>> (https://guides.github.com/features/mastering-markdown/),
>> they have added some extra features that are suitable for technical
>> documentation.
>> Here is their Writing Guidelines,
>> https://www.digitalocean.com/community/tutorials/digitalocean-s-writing-guidelines
>> which shows off their additions (second-half of the page).
>> 
>> Among the useful features they have added to Markdown (see Writing Guidelines),
>> 1. Ability to highlight text even in a code environment (for example,
>> in some configuration you can easily highlight the stuff that the user
>> needs to write)
>> 2. Ability to show the command line in five different environment
>> (themes?). If you show commands that you write on Server A, you can
>> specifically use Theme 1 and so on.
>> 3. Ability to show the output of commands in a suitable environment
>> (and also can highlight aspects of that output)
>> 4. Native notes and warnings (in standard markdown, you would need to
>> insert HTML for this)
>> 5. Have the prompt ($ or #) added appropriately because we define that
>> a command line is for superuser or plain user. Also, custom prompts.
>> 
>> There is the Web previewer to try these out at
>> https://www.digitalocean.com/community/markdown
>> 
>> I believe that the standard markdown, as described on github, is not
>> suitable for technical documentation as it lacks features.
>> An enhanced markdown would be more appropriate and more joyful to
>> write documentation.
>> 
>> For me the questions are,
>> a. what "enhanced markdown" can we get that is at least on parity with
>> Docbook XML features.
>> b. is there some tool to autoconvert Docbook XML to markdown?
>> c. will existing core technical writers be happy to switch to markdown?
>> 
>> Simos