Feedback request | Documentation site reorg, switch to Markdown

[Chris Perry]

Hi all

The volunteer writers working on the desktop help and the server guide
are Gunnar, Doug, and me. In the interests of transparency I want to
say that Peter has already discussed his proposal with us (via email).
I've only worked on the desktop help so I am only qualified to discuss
the desktop help. Of course I only speak for myself (not for Gunnar
and Doug).

I believe the current desktop help processes work pretty well (though
I'm not saying they couldn't be improved). Peter is proposing to scrap
the existing processes and replace them with new processes that in
terms of inputs (let's describe them as source files in thirty odd
languages) and outputs (let's describe them as html files and packages
in thirty odd languages) do exactly the same thing as the old
processes. But with the new processes all the source files would be in
Markdown.

I'm a newish volunteer so perhaps I can be trusted to give a new
volunteer's opinion of Markdown. To me it's just a markup language. If
I'm writing or revising a numbered list or creating a section heading
or creating a table, etc, it makes little difference to me whether
it's in Markdown or another markup language. I don't particularly like
any markup language. I'd be able to work faster if we had a
well-designed GUI front-end that hid most of the details of the markup
language.

It's not clear to me that Peter's proposal has significant benefits
for users of the documentation or people who want to contribute to the
documentation. In my opinion Peter has to provide very strong evidence
of significant benefits to get this approved.

Regards,

Chris Perry.



On 15 February 2017 at 22:54, Peter Matulis <peter.matulis at canonical.com> wrote:
> To reach a wide audience on this matter I sent to a few mailing lists.
> Apologies in advance for any collateral damage this may cause.
>
> Peter
>