Feedback request | Documentation site reorg, switch to Markdown

[Doug Smythies]

Hi Peter,

I'm only commenting on the Ubuntu Serverguide herein,
As others have covered the desktop help docs and the
installation guide quite well.

What I have to say was also covered in our off-list
pre-discussion.

On 2017.02.15 13:58 Peter Matulis wrote:

> All this would entail:
>
> - Initial conversion of all XML files to GFM (GitHub Flavored
> Markdown) [1]. Done by Canonical.
>
> 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.

For years now, you have been trying get agreement to change the
the serverguide to some sort of markdown. I have always wanted to
see a project plan, timeline, and labour estimate. Now you are saying
Canonical would do the initial work (I assume they would want
a project plan, timeline and estimate), so that community concern
is removed.

Would the mentioned mockup site and workflow include translations
workflow? Would it include a PDF mockup serverguide? In my opinion
a PDF serverguide is a must have.

> 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.

As I have said so many times now, the Serverguide is in
desperate need of subject matter expert help.

Myself, I don't think the change would make any difference to
people's wiliness to contribute. However the feedback
from Robert Young suggests perhaps otherwise.

> 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].

Good.