Feedback request | Documentation site reorg, switch to Markdown
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
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
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