Feedback request | Documentation site reorg, switch to Markdown

[Chris Perry]

Hi Peter

It sounds as if you and Doug agree that the main problem here - by far
the most important problem? - (as regards the server guide) is that
"the Serverguide is in desperate need of subject matter expert help".
Your proposal does nothing directly to address this problem. I don't
understand this. If we get the technical reviews then if necessary I
can help Doug do the updates to the server guide, Can't Canonical
provide the technical reviewers? Perhaps I'm misunderstanding
something crucial?

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