Feedback request | Documentation site reorg, switch to Markdown

[Stephen M. Webb]

On 2017-02-16 07:42 AM, Chris Perry wrote:
> 
> 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.

Switching from a semantic documentation markup to a non-semantic unstructured set of HTML macros that has wretched
support for anything other than web pages is a net negative gain. Markdown was written by coders for coders so they can
appear to have something like online documentation.  It's the wrong choice for something like a manual, API docs, or
pretty much anything more than marketing quips or blog comments.

I'm all for a consistent presentation style across Canonical-supported media and across all Ubuntu media.  I don't think
ex-cathedra forcing a workflow and markup switch onto actual writers is the right way to achieve that if you're trying
to encourage participation and quality of content.

So, agreed, I'd like to see a community-friendly discussion on the benefits of moving away from existing workflows and
structure with arguments pro and contra.

-- 
Stephen M. Webb  <stephen.webb at canonical.com>