Converting to Mallard?

[Jim Campbell]

On Wed, Apr 14, 2010 at 8:32 PM, Kyle Nitzsche
<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 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. 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.

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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20100415/a8439378/attachment.html>