Feedback request | Documentation site reorg, switch to Markdown

[Jim Hodapp]

Being part of a team that is now contributing on a weekly basis to
docs.ubuntu.com/core, 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
docs.ubuntu.com/core 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.

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.

[1] https://github.com/CanonicalLtd/ubuntu-core-docs/blob/master/README.md

On Mon, Feb 27, 2017 at 11:00 AM, Doug Smythies <dsmythies at telus.net> wrote:

> 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
>
>
>
> --
> ubuntu-translators mailing list
> ubuntu-translators at lists.ubuntu.com
> https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/ubuntu-translators/attachments/20170227/03cd7db7/attachment.html>