Feedback request | Documentation site reorg, switch to Markdown

[Simos Xenitellis]

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