Transition to Mallard?

Thomas R. Jones thomas.jones at maitreyasecurity.com
Thu Jan 21 21:50:42 UTC 2010



Sent from my iPhone

On Jan 21, 2010, at 3:11 PM, Matthew East <mdke at ubuntu.com> wrote:

> Hi Thomas,
>
> There are quite a few misunderstandings here. I'd like to try to
> correct a few of them, but your email is very long and I apologise in
> advance because I won't be able to answer every single one of your
> points. I'm choosing what I feel are the most important.
>
> On Thu, Jan 21, 2010 at 5:50 PM, Thomas R. Jones
> <thomas.jones at maitreyasecurity.com> wrote:
>> With this in mind, shouldn't we be looking at adopting Darwin
>> Information Typing Architecture rather than Mallard? It after all  
>> is an
>> accepted standard produced by OASIS since 2005.
>
> That is something that has been considered and can continue to be so.
> I'd encourage you to read this blog post in which Shaun compares and
> contrasts DITA and Mallard.
> http://blogs.gnome.org/shaunm/2009/06/17/writing-open-source/
You still did not answer the question. Don't push documents written by  
one of the proponents of Mallard. Show me facts. Non bias facts. Plain  
and simple.

I have presented entirely outside sources as examples throughout this  
discourse. Can you do the same?

>
>> I don't agree with the "topic" requirement. Easier doesn't mean  
>> better.
>> What you are implying is that by migrating to an easier(which is a
>> personal preference) topic-based construct is that it will allow  
>> authors
>> to produce more documentation. Is that a good talking point? More is
>> most definitely not better. Do we as a community want to allow more
>> documents of lesser quality to be provided to prospective users of
>> Ubuntu and its derivatives? Certainly not.
>
> Here you've made a fundamental misunderstanding. You imply that
> providing documentation in topics means that the documentation is of
> lesser quality. That's not the case. There are many ways that the
> "quality" of a document could be evaluated. The most obvious one is
> the material itself, the words. That has nothing to do with whether
> the document is in topics or guide form. Ultimately, the "quality" on
> which help falls to be judged is how useful it is to users.
>
> What interests us here is not to allow authors to produce more
> documentation. It's to produce documentation that is more helpful for
> our users.
No. You are back tracking now. You stated that docbook was too complex  
and authors do not need to learn it. You implied that Mallard with  
it's watered down XML is easier to author. You are simply totally one  
hundred percent incorrect. I would appreciate it if you would stay on  
topic.

Either it's ease of use. Or it's effectiveness. Which one? You need to  
choose.

Hint: to the end-user the underlying infrastructure is unimportant.  
They need the data!!!!

Ease of use of Mallard. Questionable. More helpful to users. A  
stalemate----it's the same content!!!! So now where should we go with  
that.

>
>> Ok. Back to the topic-based representation choice made. Who made the
>> choice to specify that topic-based is a requirement? Maybe this  
>> happened
>> before I joined the community.
>
> For the Ubuntu project's part, the decision was taken around 2005. See
> this spec: https://wiki.ubuntu.com/TopicBasedHelp and also the more
> detailed: https://wiki.ubuntu.com/HelpfulHelp which includes more
> reasoning, comparisons and research.
>
> It's absolutely clear that topic based help is easier for users to
> understand when dealing with on-screen help. It's not controversial
> and I can't see the Ubuntu doc project or the Gnome project changing
> their minds about that.
Wow. And how do you come to this conclusion? In fact, I will post  
later specific documents that in fact prove that you are incorrect.  
Truth be told, a taxonomy-based approach has always been proven to  
provide better results. The crutch with this approach is the  
complexity and vast amount of information presented. Don't believe  
me.....go to your nearest university and inquire.
>
>> When Mallard produces topic-based content does it not also utilize a
>> structure of content about the topic? There is a particular  
>> structure to
>> it. It is presented that docbook uses article or book. And mallard  
>> uses
>> page in your example in the ten minute tour. How is this different?
>> Regardless, it is XML and must have a root element. The naming
>> convention is simply semantics. Where is the advantage to your
>> presentation? How does "page" become an advantage over "article"?
>
> You need to read a bit more about how Mallard is designed. I'd
> strongly encourage you to read these pages as a minimum:
>
> http://projectmallard.org/about/index.html
> http://projectmallard.org/about/learn/tenminutes.html
I have. In fact I have been communicating with various individuals off  
list. I have brought up serious deficiencies in the proposal and will  
soon publish these to the list.
>
>> There's no need to write docs to teach people Docbook. Its pretty  
>> self
>> explanatory. For the use most likely intended to be utilized during
>> development of documentation for Ubuntu, it needs no explanation.
>
> I disagree with you, and I think that a lot of people feel like I do.
> I feel comfortable using docbook, but it took me some time to learn it
> and it can look very daunting to our contributors, many many of whom
> are not used to development tools.
Come on. Docbook is no different than Mallard. It is an XML format. So  
because Docbook is "daunting" so must Mallard be by implementation of  
the property of transference(yeah...finally a math minor is worth it).  
You simply alter some of the elemental names. You need to bring better  
arguments to the table than that.
>
> {snipped a lot of material because it addresses features which we do  
> not use}
Why is this? These represent facets of docbook that are  
internationally recognized. So now because Mallard does not use them  
they are unimportant? I think thousands of developers around the world  
would be up in arms about your stance. After all we are talking about  
XML and it's related technologies----correct?
>
>> Huh? How do you add topics without altering the original sources?  
>> This
>> statement actually intrigues me....
>
> This is the key and unique feature of Mallard. If you haven't got
> that, it means that you haven't read the two pages linked above and I
> would really encourage you to do so. It's the only way to have an
> informed discussion about this.
Again, myself and others are currently in discussion about this.
>
>> Somewhere in this thread I read about needing to accommodate our
>> upstream provider Gnome. Now I realize you work for gnome , but what
>> about the KDE side of our upstream? They use Docbook ---- No? Further
>> more, what about our most critical upstream provider ---- the Linux
>> kernel. I believe that upstream provider utilizes Docbook. As well  
>> does
>> the entire Linux Documentation Project.
>
> We produce desktop help - we don't use any material from the Linux
> Documentation Project and I wouldn't regard them as an upstream
> provider for us at all, let alone a critical upstream provider.
Are you serious? The LDP is not an upstream project? Who do you think  
provided end-user support in Linux infancy? Who carried the community  
while it was still just academia? These resources provide a basis and  
a root of the community. Not just some fly-by-night group of people in  
a conference room. A cornerstone of all documentation projects  
worldwide. You might want to rethink your stance on this.
>
> KDE is definitely an issue for us and I'm looking forward to see how
> discussions between Gnome and KDE about how to collaborate on desktop
> help will pan out.
At least we can agree on this. I forsee this coming down to which WM  
has the most corporate backing. Money speaks wonders. Even in open  
source projects.
>
> -- 
> Matthew East
> http://www.mdke.org
> gnupg pub 1024D/0E6B06FF




More information about the ubuntu-doc mailing list