Feedback request | Documentation site reorg, switch to Markdown

Doug Smythies dsmythies at
Mon Feb 27 16:00:01 UTC 2017

On 2017.02.22 16:47 Peter Matulis wrote:

> I should mention to the uninitiated that a single wayward character will generate
> a bewildering error when a build of HTML is attempted. Considering that you need
> to go through a long file full of the above stuff, I recall my "debugging" sessions
> consuming a large amount of my time, not to mention the frustration.

Very true, and a good point.
Debugging some mistake is very very annoying and time consuming.
In terms of warnings and error messages, I have no experience with the proposed
Markdown method.

> Is there ANYONE out there that has written a significant amount of material for the Server
> Guide and also believes we should stick with XML/Docbook? These are the people I
> especially want to hear from.

Either way, I'd still like to hear from Serge Hallyn, Ted Cox, Christian Ehrhardt, Nish Aravamudan,
Simon Quigley, Ian Nicholson.

> I believe that XML is technically superior to Markdown and it definitely has advantages,
> but only when used in certain contexts. A good example is a single author, or a team of
> dedicated people, writing for a project, like an O'Reilly book, for instance. However, our
> contributors come and go. Each wants to help but very few will take the time to understand a
> difficult format unless they expect to do sustained writing. This is just not our reality. What
> we're trying to solve here is:
> Find a format that the average person can use to write new material for Ubuntu Server without
> having to devote an inordinate amount of time learning compared to the time they will spend writing.

... Doug

More information about the ubuntu-server mailing list