Feedback request | Documentation site reorg, switch to Markdown

[Peter Matulis]

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.

Peter

On Wed, Feb 15, 2017 at 4:58 PM, Peter Matulis
<peter.matulis at canonical.com> 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,
> docs.ubuntu.com, that would link to all these documentation sites.
>
> 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.
>
> 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]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
> [2]: https://github.com/CanonicalLtd/documentation-builder
> [3]: https://creativecommons.org/licenses/by-sa/4.0/