Feedback request | Documentation site reorg, switch to Markdown

Ian Nicholson ian at binaryash.net
Tue Feb 28 04:41:10 UTC 2017


On 02/27/2017 10:00 AM, Doug Smythies wrote:
> Either way, I'd still like to hear from Serge Hallyn, Ted Cox, Christian Ehrhardt, Nish Aravamudan,
> Simon Quigley, Ian Nicholson.

Speak my name and I appear.

I'll cop to having almost no experience with markdown, so my concerns 
would be:
1 - Are we losing semantic information by switching?  One thing I like 
about the current server guide is that we can do note/warning/info 
sections, will we be able to replicate that with markdown?  Will 
markdown maintain at least equivalent support for a11y tools?  Is a11y 
even relevant when we're talking about authoring documents rather than 
displaying them?
2 - Will we be able to validate that the structure of the document(here 
I'm referring to the formatting) is correct like we do with Docbook?  As 
ugly as the errors are, I never have a doubt whether what I write is 
going to render correctly when I use Docbook.

One thing I noticed about contributing is that when I went looking there 
wasn't a really good xml editor.  I think I ended up using gedit but 
there were some pain points.

Overall though I really like Docbook and I'd hate to see it go. Markdown 
seems like a good language for doing simple display stuff, but Docbook 
is really versatile.
If the ultimate goal is to encourage contributions, I think it would be 
more effective to work on offering reasonable tasks to newbies. At least 
when I started, I was pretty overwhelmed with how much work needed to be 
done; the format of the documentation was the least of my worries.

P.S.  I'm not sure if this will make it through the distribution lists 
due to SPF/DKIM/DMARC, Doug or Peter could you please forward it on if 
it gets caught in spam filters?  Thanks.



More information about the ubuntu-server mailing list