<div dir="ltr">Being part of a team that is now contributing on a weekly basis to <a href="http://docs.ubuntu.com/core">docs.ubuntu.com/core</a>, I can confidently mention that what we are doing with these contributions has been working out nicely. We have a use case of needing to contribute high quality documentation that is updated on a regular basis for our commercial IoT customers. To meet this goal, we've basically made documentation a required piece for every merge/pull request for the snaps that we maintain for our commercial customers (obviously there are a few exceptions where this doesn't make sense). We laid things out in a tree structure that integrates nicely with documentation-builder, yet facilitates our team's need to update the documentation rapidly by being able to peer-review the documentation within our own team. For these reviews, we are making sure to follow a common style guide. Also of importance to highlight is that we store the documentation, written in Markdown, right in each snap's git repository alongside of the code. We've created a standard directory structure for this and we aggregate this up to <a href="http://docs.ubuntu.com/core">docs.ubuntu.com/core</a> with the use of git-repo. Take a look at the README.md for how simple this is to work with for generating the final docs [1]. I can't emphasize enough how easy this structure is to work with and how well it has scaled for our needs thus far.<div><br></div><div>It might not be the right model for every use case, but it should be a very good fit for the majority of use cases surrounding Ubuntu. Markdown is an absolute pleasure to work with which is a critical point. We developers generally hate writing documentation and so making it as frictionless as possible is a very high ideal - one that I think Markdown facilitates quite nicely. </div><div><br></div><div>[1] <a href="https://github.com/CanonicalLtd/ubuntu-core-docs/blob/master/README.md">https://github.com/CanonicalLtd/ubuntu-core-docs/blob/master/README.md</a></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Mon, Feb 27, 2017 at 11:00 AM, Doug Smythies <span dir="ltr"><<a href="mailto:dsmythies@telus.net" target="_blank">dsmythies@telus.net</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">On <a href="tel:2017.02.22%2016" value="+12017022216">2017.02.22 16</a>:47 Peter Matulis wrote:<br>
<br>
> I should mention to the uninitiated that a single wayward character will generate<br>
> a bewildering error when a build of HTML is attempted. Considering that you need<br>
> to go through a long file full of the above stuff, I recall my "debugging" sessions<br>
> consuming a large amount of my time, not to mention the frustration.<br>
<br>
</span>Very true, and a good point.<br>
Debugging some mistake is very very annoying and time consuming.<br>
In terms of warnings and error messages, I have no experience with the proposed<br>
Markdown method.<br>
<span class=""><br>
> Is there ANYONE out there that has written a significant amount of material for the Server<br>
> Guide and also believes we should stick with XML/Docbook? These are the people I<br>
> especially want to hear from.<br>
<br>
</span>Either way, I'd still like to hear from Serge Hallyn, Ted Cox, Christian Ehrhardt, Nish Aravamudan,<br>
Simon Quigley, Ian Nicholson.<br>
<span class="im HOEnZb"><br>
> I believe that XML is technically superior to Markdown and it definitely has advantages,<br>
> but only when used in certain contexts. A good example is a single author, or a team of<br>
> dedicated people, writing for a project, like an O'Reilly book, for instance. However, our<br>
> contributors come and go. Each wants to help but very few will take the time to understand a<br>
> difficult format unless they expect to do sustained writing. This is just not our reality. What<br>
> we're trying to solve here is:<br>
><br>
> Find a format that the average person can use to write new material for Ubuntu Server without<br>
> having to devote an inordinate amount of time learning compared to the time they will spend writing.<br>
><br>
<br>
</span><span class="HOEnZb"><font color="#888888">... Doug<br>
</font></span><div class="HOEnZb"><div class="h5"><br>
<br>
<br>
--<br>
ubuntu-translators mailing list<br>
<a href="mailto:ubuntu-translators@lists.ubuntu.com">ubuntu-translators@lists.<wbr>ubuntu.com</a><br>
<a href="https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators" rel="noreferrer" target="_blank">https://lists.ubuntu.com/<wbr>mailman/listinfo/ubuntu-<wbr>translators</a><br>
</div></div></blockquote></div><br></div>