Feedback request | Documentation site reorg, switch to Markdown

[Peter Matulis]

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/