Converting to Mallard?

[Kyle Nitzsche]

Hi again all,

At the risk of being redundant, my personal view is that the doc team 
and community are doing great work and every point I make is my two 
cents to try to help out.

See below.


On 04/15/2010 07:54 AM, Jim Campbell wrote:
>
>
> On Wed, Apr 14, 2010 at 8:32 PM, Kyle Nitzsche 
> <kyle.nitzsche at canonical.com <mailto:kyle.nitzsche at canonical.com>> wrote:
>
>     On 04/14/2010 09:24 PM, Shaun McCance wrote:
>     > On Wed, 2010-04-14 at 19:49 -0400, Kyle Nitzsche wrote:
>     >
>     >> Hi Phil and all,
>     >>
>     >> 1) Does this approach (using upstream/Gnome help and adding
>     >> Ubuntu-specific content to stub locations therein) support removing
>     >> upstream content? It seems likely, or at least possible, that some
>     >> upstream content might, for whatever reason, be inappropriate
>     for Ubuntu
>     >> (and/or its variants, of which there are many and of which
>     there will in
>     >> all likelihood, be many, many more).
>     >>
>     >> 2) Is the upstream/Gnome content really the best for Ubuntu?
>     Even though
>     >> it may simplify development and maintenance, the value to the
>     Ubuntu
>     >> user should perhaps be a higher priority. There should be a
>     systematic
>     >> analysis of Gnome help content with discussion to determine
>     whether it
>     >> is right for Ubuntu before serious considering it.
>     >>
>     > I'm not going to address what's best for Ubuntu, its users,
>     > or its contributors. But I do want to point out that Phil
>     > is the primary person driving the new Mallard-based Gnome
>     > help right now. It's not a matter of taking some black box
>     > from some nebulous "other" provider. Distro people can, do,
>     > and absolutely should shape upstream software.
>     >
>     I support Phil, you and the community. The amount of work you all
>     do is
>     truly exceptional.
>
>     I just want to see a more complete analysis of the options. If the
>     approach doesn't allow for customization, then that's an issue for me.
>
>
> Kyle, I think it would be helpful for you to provide specific examples 
> of the customizations that you require.  I think I recall you saying 
> that some Ubuntu derivatives didn't want to ship the Ubuntu help.  Can 
> you say why?  What specific needs would need to be addressed?  What do 
> they need to customize?
I am very happy to see in Lucid the completely rewritten New To Ubuntu 
topic, and that it closely follows the draft I proposed to the list 
(http://people.canonical.com/~knitzsche/ubuntu-getting-started-guide/index.html) 
(with prototype here: 
http://people.canonical.com/~knitzsche/ubuntu-getting-started-guide/index.html). 


As noted in that email, that topic is particularly well suited to being 
treated as a customizable component. That is, different Ubuntu variants 
do have different application sets (one might use Evolution, another 
Thunderbird. One might use Network Manager, another Connection Manager, 
etc). In addition, it is a perfect place to offer customized welcome 
messages. It can easily be launched in Yelp on first boot and still be 
seamlessly integrated into the Ubuntu Help Center, exactly as it is 
today. The approach would be to package it separately. That way, this 
one topic can be forked without having to fork *all* of Ubuntu Docs. (I 
have pointed out that Ubuntu Docs is "monolithic" here before.) Should 
this approach be taken, there are open questions about packaging 
translations that need to be evaluated. Still, I propose that as a 
*general goal*, docs should be more modular in their packaging to enable 
remixing content into variants. We simply need to start to treat ubuntu 
docs not as an end it itself for Ubuntu, but as an *upstream* to Ubuntu 
variants.

>
>     I still wonder about some previous issues I've raised respecting
>     Mallard:
>      * what control over user submitted topics (might the user confuse
>     them
>     with official docs and can the user revert to official docs?)
>      * translation regressions and new work (all of which may be worth it)
>      * control of the order of topics
>
>     >
>     >> I've spoken before advocating development of a "true north" for
>     Ubuntu
>     >> Docs that expresses a set of high level priorities so that
>     decisions can
>     >> be well and publicly made. I would rank highly utility (to the
>     user) and
>     >> customizability (to support Ubuntu variants). Secondary (but
>     still very
>     >> important) items include, for me, work load. That is, a system that
>     >> meets top priorities may well involve more work, but that work
>     may be
>     >> justified.
>     >>
>     > My top priority is always to help users as best as possible.
>     > That should be the top priority of everybody working on user
>     > assistance. But when working with volunteer communities, you
>     > have to balance that with what people can reasonably provide
>     > without getting burned out.
>     >
>
>
> At this point I think Mallard is a big step up from DocBook (easier to 
> write with and provides easier customizations) but it isn't yet at the 
> hardcore content reuse / customization level of DITA.  It also isn't 
> nearly as complex to write with as DITA.  While there are discussions 
> on the Mallard list to bring in additional abilities for 
> customization, I'm concerned that doing so will take away some of the 
> simplicity that makes Mallard appealing to writers.
>
> As Shaun indicated, we have to keep in mind that we're working with 
> volunteers.  We've seen people voluntarily pick up Mallard and start 
> writing their help with it.  Could we expect people to do the same 
> with DITA?  Would a developer write their own help in DITA? I don't 
> think they'd have the time to learn it.

I am gradually coming to support this viewpoint based on your points and 
those made by the others on this list.
> Similarly, on the Mallard front, we would need to be mindful of the 
> costs of added complexity as we try to address the customization issues.
So Mallard allows plug in content. If that content is separately 
packaged in a reasonable way then customizability is accomplished. (All 
of this applies to docbook too.)

Imagine one package that delivers the main guide page content.
Imagine other packages for each main topic.
Guide pkg depends on topic packages.
To customize a topic package, you just make your own version. (To 
customize the guide page, you just customize that)

If you want the content of any pkg as is, you simply don't make your own 
version of it.
Again, this kind of approach would need to be integrated with language 
issues.

This enables Ubuntu variants to easily modify help to match whatever 
part of the system they happen to have modified while taking the rest as is.

If the approach works, then why not treat all topics as separate 
packages? At any rate, we could start with ONE pkg: New to Ubuntu, as a 
trial run.

>
> A way around all of this might be to look at workflows and tools - For 
> example, having people write docs in a wiki, and then have the doc 
> team do the conversions, or to use an open-source help authoring tool 
> like Serna.
>
> It seems that part of the issue is that Ubuntu and Gnome are growing 
> and gaining popularity, so people expect more sophisticated help.  At 
> the same time, there is greater need for customization by derivatives 
> (at least, it seems, for derivatives of Ubuntu).  How do we address 
> these changes while being realistic about working with people who are 
> volunteers and who are not always familiar with technical writing?
>
> I think the group also needs a timeline for making these decisions.
>
> Jim
>
> P.S.  Yes, I'm still just lurking these days.