Feedback request | Documentation site reorg, switch to Markdown

Milo Casagrande milo at
Thu Feb 16 07:56:48 UTC 2017

> On Wed, Feb 15, 2017 at 4:58 PM, Peter Matulis
> <peter.matulis at> wrote:
> For, each help topic (Server, Desktop, and
> Installation Guide) would get their own page (e.g.
> help.u.c would continue to exist solely for
> the help wiki, which is not documentation.

Just to be clear: this would mean that everything under lp:ubuntu-docs
would be converted to github-markdown, right?
Would that include other Ubuntu flavors?

(disclaimer: I'm not involved in the Ubuntu Docs team, so what I'm
saying might be wrong or not true anymore)
IIRC, some parts of the Ubuntu documentation are shared with/based on
GNOME documentation; if ubuntu-docs were to switch to a Markdown-based
syntax as the primary choice for writing documentation, I think it
might get hard to contribute back or be able to use the work done by

So, would this [xml|mallard]→Markdown conversion be final, or would it
still be possible to work with [xml|mallard] and convert it to
Markdown when necessary?
I'm trying to figure out how the workflow would be...

> - Initial conversion of all XML files to GFM (GitHub Flavored
> Markdown) [1]. Done by Canonical.
> - New and actively maintained doc builder [2]
> - Streamlined build and publication processes
> - A common theme
> - Contributions from the Canonical Docs Team members to the current
> help.u.c projects (personal time)
> - Multiple build formats across the board (where appropriate)
> For contributors, workflow changes would be:
> - Write in Markdown
> - Use a different build tool (local building to verify HTML)

What about translations?
Is there already a markdown-2-po extractor? Personally I've never seen
one, but I also haven't looked for one.


Milo Casagrande <milo at>

More information about the ubuntu-server mailing list