ubuntu-manual team mailing list archive

[Jim Campbell <jwcampbell@xxxxxxxxx>]

Hi all,

On Thu, Jul 1, 2010 at 3:31 PM, Kyle Nitzsche
<kyle.nitzsche@xxxxxxxxxxxxx>wrote:

> Hi All,
>
> Just chiming in with my two cents for your consideration...
>
> Wondering how this plan coordinates with the (lofty) goal that was
> discussed with great enthusiasm at Maverick UDS of creating a common
> pool for documentation source, where the Ubuntu Manual project and the
> Ubuntu Docs project can house doc source material, thereby supporting
> common usage and enabling all the good bits that derive from that, such
> as single-source maintenance, reusability, higher quality (since errors
> need to be corrected only once), but most importantly, improving the
> user experience through support of remixed content into exciting new
> contexts.


>From what I understand, the manual team was looking to do this for
Maverick+1.  There was much discussion initially, but things seem to have
quieted down, at least on their mailing list.  I'm not sure what is going on
with that project now, but I'm copying their list in hopes that we'll get a
reply here.


> Since there is currently no docbook -> mallard converter (be
> it through xslt or whatever), then that goal is made more problematic
> and distant, it would seem. Since this was a topic of high interest at
> UDS, this deserves some explicit consideration here, it would seem.
>
>
With regards to docbook -> mallard conversions, from my experience, creating
topic stubs in Mallard makes it very easy to "stub-out" documentation,
allowing new contributors to easily see what needs to be done, and to dig
in.  This helps to alleviate the, "Where can I start?  What needs to be
done?" question that confronts new contributors.  I think we'd be able to
get a lot of new content fairly quickly using Mallard, even w/o conversion
scripts.



> There were discussions previously on this list about the impacts
> (regressions) that conversion from docbook to mallard would have on
> existing Ubuntu Docs translations, namely that inline tags are often
> different (between docbook and mallard), which means the source strings
> are different, which means existing translations break. So that is a
> potential regression that probably should be identified up front with
> some kind of fact-based analysis (5% of strings, or 50%?) that gives
> some idea of the extent of translation regression that may occur, at
> least to enable Ubuntu Translators to understand what kind of additional
> work to expect. If much of this can be avoided by writing a clever
> conversion script, then that should be identified as an important piece
> of work, it would seem.
>

Others have commented on this over the past several days.


>
> Also, see below...
>
> On 06/30/2010 11:10 AM, Phil Bull wrote:
> > Hi Jim,
> >
> > On Wed, 2010-06-30 at 09:51 -0500, Jim Campbell wrote:
> >
> >> So did we want to go ahead with using Mallard for this release of
> >> Ubuntu docs?  Phil, if I recall correctly, didn't you have a branch of
> >> Ubuntu docs containing page stubs from our prior release?
> >>
> > I think we should go ahead with the Mallard conversion. I looked around
> > for a branch containing stubs, but I didn't find one. Who knows what I
> > did with it?
> >
> > Ideally, we would coordinate with the GNOME doc team; we should slot our
> > docs into their Desktop Help. That's in a very early stage of
> > development at the moment, though. For now, we should probably just
> > identify clearly Ubuntu-specific areas of our own docs and convert
> > those.
> >
> >
> The Ubuntu desktop experience is sometimes different from a pure Gnome
> one, at least until Ubuntu innovations like notifications, window
> buttons, and panel items like networking, about me, and power management
> are adopted in gnome (I think I got that list right...). So this idea of
> "slotting in" of ubuntu docs into gnome docs may result in two
> explanations in such areas: if on Gnome, it's like this, if on Ubuntu,
> like this, which seems less than ideal. I continue to wonder whether it
> makes more sense to have an Ubuntu Docs framework that "slots in" gnome
> docs as appropriate, which, I realize, is how it is currently done.
> There is no technical barrier to including mallard content in docbook
> source that I know of.
>

Let's tell Mark that Ubuntu has to use vanilla Gnome from here on out!  :-P


Kyle makes a good point, but it is one that we will need to be mindful of at
a topic-by-topic level regardless of what syntax is being used.


>
> > It would be helpful to convert all of the existing DocBook into plain
> > text first. I find that much easier to deal with when doing a
> > conversion. I'll set-up a branch with Mallard .page stubs and dump the
> > text-only topics into the .page files. That should provide a good
> > starting point.
> >
> > To help the process along, would anyone be interested in a Mallard
> > training session on IRC?
> >
> > Thanks,
> >
> > Phil
> >
> >
> Cheers,
> Kyle
>
>
I'm in favor of having a content pool in place for Ubuntu, but realistically
. . .  would something be ready for Maverick+1?  I'm not so sure.  With a
content pool, we're essentially talking about creating a CMS for Ubuntu
docs.  I do think it is a good idea, and I do think we should plan for it,
but I also think it is easier said than done, and I'm wary of trying to roll
our own.

Given that we have no CMS at this point, and that we don't have a concrete
plan in place as to when we will have one (*and* when it will be production
ready for all workflows, including translations), at this point I don't
think it would be good to stay with the status quo until the CMS is ready.
I say that even with Kyle's caveats (which I appreciate) in mind.

Please feel free to share other comments.  Thanks, all.

Jim