Feedback request | Documentation site reorg, switch to Markdown

[Chris Perry]

Hi Peter

Yes I object to your proposal to move the server guide to Markdown.

I've never worked on the server guide until today but it was
straightforward for me to set it up, do a simple edit to one of the
xml files, generate the html files, and check my change using a
browser. I did have the advantage that I was already set up for bzr,
ssh, and Launchpad and I can see that the requirement to use bzr, ssh,
and Launchpad could put people off - but you're not proposing to
change those I think.

My opinion is that it's too much to ask one-off contributors to go
through the bzr/ssh/Launchpad/xml process or the
bzr/ssh/Launchpad/Markdown process but that anyone who is willing to
do a series of contributions can learn either easily enough. We have
xml for the server guide at present so why expend the effort to switch
to Markdown?

Regards,

Chris.

On 20 February 2017 at 00:38, Peter Matulis <peter.matulis at canonical.com> wrote:
> 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
>
> --
> ubuntu-doc mailing list
> ubuntu-doc at lists.ubuntu.com
> https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc