Feedback request | Documentation site reorg, switch to Markdown

[Robert Young]

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
> 
> -- 
> ubuntu-server mailing list
> ubuntu-server at lists.ubuntu.com
> https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
> More info: https://wiki.ubuntu.com/ServerTeam