Feedback request | Documentation site reorg, switch to Markdown
milo at ubuntu.com
Thu Feb 16 07:56:48 UTC 2017
> On Wed, Feb 15, 2017 at 4:58 PM, Peter Matulis
> <peter.matulis at canonical.com> wrote:
> For help.ubuntu.com, each help topic (Server, Desktop, and
> Installation Guide) would get their own page (e.g.
> docs.ubuntu.com/server). 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) . Done by Canonical.
> - New and actively maintained doc builder 
> - 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 ubuntu.com>
More information about the ubuntu-server