Feedback request | Documentation site reorg, switch to Markdown

Peter Matulis peter.matulis at
Wed Feb 15 22:54:08 UTC 2017

To reach a wide audience on this matter I sent to a few mailing lists.
Apologies in advance for any collateral damage this may cause.


On Wed, Feb 15, 2017 at 4:58 PM, Peter Matulis
<peter.matulis at> wrote:
> All,
> This is a request for feedback from the community.
> There is a proposal put forward by Canonical to provide a consistent
> look and feel for all Ubuntu documentation, regardless of whether it
> is primarily maintained by the Community or by Canonical. The idea is
> that this will provide a better user experience for the reader. The
> process of building and publishing would also change so that all
> projects will use the same method. Not only will this make it easier
> compared to current methods but it will allow people to work on
> different projects using the same workflow and toolset.
> Currently, the "Canonical docs" consist of MAAS, Juju, Ubuntu Core,
> and Landscape. There is a central doc site under construction,
>, that would link to all these documentation sites.
> 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.
> All this would entail:
> - 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)
> It is my hope that moving to Markdown will act as a catalyst to get
> people to contribute to docs again. It is certainly more user-friendly
> than the two forms of XML currently in use.
> Launchpad and Bazaar will continue to be used for the current help.u.c
> topics, mostly due to translations.
> Canonical could create a mockup site of the Server Guide to show what
> all this would look like, including at the commit, build, and publish
> levels.
> Note that documentation for the Canonical-sponsored projects is
> available for contributions from the community (minus
> internationalization at this time) and will be published according to
> CC BY-SA 4.0 [3].
> Thanks for listening,
> --
> Peter Matulis,
> Documentation
> Canonical Ltd.
> [1]:
> [2]:
> [3]:

More information about the ubuntu-server mailing list