Xfce user help (aka documentation) writers needed

[Jim Campbell]

Hi All,

On Mon, Mar 1, 2010 at 4:07 PM, Russell Dickenson <
russelldickenson at gmail.com> wrote:

> On 2 March 2010 03:59, edoceo <code at edoceo.com> wrote:
> > On Mon, Mar 1, 2010 at 3:34 AM, Russell Dickenson
> > <russelldickenson at gmail.com> wrote:
> >> I'm curious about whether there's been any progress on Xfce's
> >> documentation? If I can spare some time I would like to contribute.
> >> Should I be looking elsewhere for the work's current status?
> >>
> >
> > Russell,
> >  Here is a great place to start; we've been having some rumblings
> > about documentation over the last few weeks and (I'm sure) would
> > welcome the assistance.
> >
> >  It appears that documentation for Xfce 4.6 will be moving forward
> > using a tool called Mallard (not set in stone as of yet, AFAIK).  I
> > think the first step would be to take a look there - it's a straight
> > forward XML system.  http://projectmallard.org/
> >
> >  And, you can see it first hand by looking in the git repository for
> > panel here: http://git.xfce.org/xfce/xfce4-panel/tree/docs
> >
> > /djb
>
> Can someone please explain why we might be following the Mallard path?
> If I understand correctly - from disjointed readings of GNOME blogs
> etc - the GNOME project developed Mallard specifically for integration
> between documentation and Yelp. Since Xfce doesn't have Yelp, I'm
> curious about why Mallard might be chosen over other methods.
>
>
Mallard was chosen due to it's emphasis on writing in a task-based manner
(individual help-topics rather than being book-oriented with docbook), the
simplicity of its syntax (fewer, simpler block elements than docbook), it's
modularity (auto-linking between related help topics), and a couple of other
features.  For example, it can be translated using existing translation
tools (xml2po, transifex).

With regards to Yelp, the Xfce team planned to initially output the help
docs to HTML.  In the long-run, yelp's developer is going to be splitting
yelp up into both an application and a back-end library.  Jannis Pohlmann of
the Xfce team was satisfied with the dependencies for the library, so an
opportunistic Xfce hacker could build an Xfce front-end on the yelp
library.


> I'm not anti-Mallard, but I am frustrated about the lack of
> information about Mallard - especially at the project's web site. It
> consists of a few examples, but very little more than that. In the
> meantime the GNOME documentation team are progressing documentation
> for some of the GNOME applications. I am left wondering - what
> references (documentation) are they using when writing? Perhaps I am
> being too demanding of a promising new project, but if you develop a
> new documentation tool, surely its documentation should be the first
> task completed?
>
>
Keep in mind that the projectmallard.org site has primarily been the work of
one person, Shaun McCance.  But, point-taken . . .  more info and content
could be added to the site.  If you noted any deficiencies in particular,
let me know.

As for how people have been writing Mallard-based docs, people have been
writing docs by following examples of other existing Mallard docs, looking
at the projectmallard.org website, and by looking at the Mallard schema
itself.  The Empathy documentation is probably the best documentation set
out there right now, and I know it was a big help for me in getting things
situated.


> My only experience to date with markup tools for documentation is with
> ASCIIDOC. Without knowing the goals of Xfce's documentation I can't
> comment on ASCIIDOC's suitability or not for the task.
>
>
I discussed python-sphinx as a possible doc format with members of the team,
but we decided against it due to the translation issue.  There are a lot of
tools out there to assist with translating XML-based docs, and the one that
we are using (Transifex) is getting a lot of developer attention.  Similar
tools just don't exist for ASCIIDOC or python-sphinx/reStructuredText.

I need to apologize to the group, though.  My work situation has required me
to put docs on the back-burner.  If others can step up to help me, we can
still get stuff done for 4.8.  I know that I just can't promise to be a
single-handed driving force behind a doc effort at this time.

That being said, let me know if you're available to meet to discuss docs
this Sunday.  If people are available, we can schedule a meeting on IRC.  We
should be able to get a meeting time set by Wednesday or (at the latest)
Thursday, and then get word out to request assistance.

Best,

Jim
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.xfce.org/pipermail/xfce4-dev/attachments/20100301/10e4af6f/attachment.html>