Feedback request | Documentation site reorg, switch to Markdown

[Peter Matulis]

On Sun, Feb 19, 2017 at 2:25 PM, Doug Smythies <dsmythies at telus.net> wrote:

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

Yes, it would include translations.

Yes, it would include a PDF.

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

Yes, I know. :(

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

The argument about how the GNOME project uses XML is significant.
There was something said about the help facility included on the
desktop image. I'm not sure how that fits in but apparently moving to
Markdown will interfere. I don't understand the statement that
"Markdown doesn't work well with images" but I don't need to know
since there are enough reasons to keep the Desktop on XML.

I believe we still have a chance to revive the Server Guide however.
No, I do not have any scientific proof or psychological studies done
that will guarantee that Markdown will make things better but I don't
think we need to worry since contributions have been so low these last
few years. I'll start the SG mockup project.

As for the Installation Guide, it could benefit from being part of the
family. I'll inquire into the feasibility of converting it.

Apart from workflow and build procedures there is still the question
of appearances. Even if one, two, or all three projects (D, S, IG)
remains as they are there is value (I believe) in herding them
together (theme and URL space). I'll look into the possibility of
doing this.

Any objections?

Peter Matulis