Re: some feedback about mallard after converting gnome-bluetooth

[Shaun McCance <shaunm gnome org>]

On Sat, 2009-07-18 at 19:42 +0200, Baptiste Mille-Mathias wrote:
> Hello there,
> 
> as some of you may know I've just converted the documentation of
> gnome-bluetooth using the mallard format.
> the repository is
> http://gitorious.org/gnome-bluetooth/gnome-bluetooth/commits/mallard-doc
> 
> I wanted to take advantage of this to send the problem I encountered, I
> certainly mixed bugs falling under yelp, mallard and gnome-doc-utils.
> 
> by the way, I'm not really used to write documentation so my comments
> are likewise to totally irrelevant.

Thanks for the feedback.  One of my primary goals with
Mallard is to make something that's easy to people who
don't eat XML for breakfast.  Far from being irrelevant,
your feedback helps me shape Mallard.

> - <list> cannot be used within <p> markup: it seems weird to me as it
> was possible with docbook. So currently I need to close <p> before and
> do my list out of the paragraph. Is it a bug?

That's an intentional design decision.  I understand
lists often logically belong to a leading paragraph,
but that semantic relationship is rarely conveyed in
the formatting.  There's a very hard rule in Mallard
that inline and block content is never mixed.  This
really makes a lot of things substantially easier.

> - no picture is showing up when using <media>: I use something like
> <media type="image" mime="image/png" src="figures/bluetooth-applet.png">
> <p>The <app>gnome-bluetooth</app> blah foo .....</p>
> </media> in various places and no picture is showing up. Do I use
> <media> correctly?

The URL resolvers aren't hooked up correctly in Yelp
yet.  It's a known bug.

> - text inside <p></p> inside <media></media> can't be selected (perhaps
> not related to mallard).

That's alt text, which you're only seeing because you're
not seeing the image.  In Gecko, alt text isn't selectable.

> - I don't like color for <steps>, the blue background doesn't fit in my
> dark theme :)

Steps are shaded for scannability.  Readers often skip
introductions and explanations and go straight for the
steps.  The exact coloration is open to discussion.  I
seem to remember it being gray, not blue.  It could be
I just have some bad color-computing code.

> - Will Mallard have a equivalent for question related markup, I always
> find convenient to have FAQ in help document. I used one in
> gnome-bluetooth docbook format, but I had to drop this part for now.

Q&A sessions are one of the things I punted on for the
time being.  It's possible it might be added after 3.0.

> The mallard format is nice to use, the conversion is quite easy.
> I have difficulties to understand the properties explained in the
> documentation (perhaps this is exhibited by the fact I don't know
> relax-ng).

The attributes should all be explained in the notes.
Are the descriptions not clear?  It could be some of
them would be more clear with more background info,
which I plan to write.

Please speak up whenever anything isn't clear.  My top
goal is to make this as easy as possible for everybody.

--
Shaun