Xfce documentation note (kind of long)

[Jim Campbell]

Hi All,

I know it's been a little bit since we discussed documentation, and I
apologize for the delay in getting things started.  I spoke with
Jannis fairly extensively prior to attending a small open source user
assistance conference in the middle of June, and we had decided to
wait on setting up any kind of doc infrastructure until I attended
that conference.

Although the Xfce team has extensively discussed a markup for the Xfce
docs, I'd like to give my take on what our options are since returning
from the doc conference.  Other than docbook, we have options with
DITA, reStructuredText+Sphinx, and Mallard.  I'll cover each of them
in turn.

DITA:
DITA is an xml-based markup that is available under an Apache license,
and currently has a great deal of support in the professional
technical writing / User Assistance world.

The Upsides:
* Unlike docbook, DITA was built to natively handle topic-based help
and conditional text.  With regards to conditional text, DITA allows
you to have just one document with (for example) instructions for both
BSD-based and Linux-based systems, but then generate customized
BSD-specific or Linux-specific documents at build-time. Having this
option available can be helpful when you are writing documentation for
different software versions or different end-user scenarios.
* Learning and using DITA would translate well for people who wanted
to build skills in the FLOSS technical writing world, and then bring
those skills to a professional writing career.

Downsides:
* The syntax for DITA, while not as vast as that of Docbook, isn't
necessarily easier to learn than the Docbook syntax.
* Authoring documentation for DITA is a bit more difficult than
authoring for docbook because you have to architect your content for
re-use.  Content architecture is one thing in a professional
environment, but it is another thing when working with unpaid
volunteers.  While we want to produce good documentation, we also want
to avoid avoidable barriers to entry.
* DITA uses ANT for its build files, and would require a slightly
different toolchain than what is used by other Free and Open-Source
documentation projects.
* There are currently a large number of applications available to
assist with the authoring of DITA-based documentation, unfortunately,
almost all of the authoring software is proprietary.

As a reference, here is the architectural specification for DITA:
http://docs.oasis-open.org/dita/v1.1/OS/archspec/archspec.html  Also,
here is the language (syntax) specification... It has all of the
nitty-gritty code snippets:
http://docs.oasis-open.org/dita/v1.1/CS01/langspec/ditaref-type.html


ReStructure Text + Sphinx:
We're pretty familiar with this by now, but I'll provide a quick summary:

The Upsides:
- It's easy to get started with rST+Sphinx. I was able to get
rST+Sphinx pages up and running in about 10 minutes.  The syntax is
really simple, and building pages out to html is simple, too.
- Decent, themeable appearance.
- Includes search functionality via javascript.

Downsides:
- Non-modular: rST+Sphinx doesn't accommodate the modularity of Xfce.
I'll discuss this further in my next point, but you can't build
rST+Sphinx pages on the fly if you add or remove Xfce components.
We'd need to have one or two "xfce-docs" packages (maybe one for
core-xfce software, and another for lesser-used programs?) that would
include everything from panel applet and xfce-goodie docs to Thunar
and xfwm4 docs.
- Translations: While it isn't a major concern (and I know we've
discussed it before, and you've indicated that it wasn't a major
concern), the rST syntax doesn't allow for use of any assistive
translation tools.  We'd just need to copy the syntax from one
document to another, and then type out the docs in our other
languages.


Mallard:
This is the new xml-based syntax that is getting a lot of uptake in
the GNOME world right now, and I saw demonstrations of it at the
writing conference that I attended a few weeks ago.  It has a couple
of advantages over docbook, but a few other concerns that are still
worth discussing.

The Upsides:
- It has been developed by the leader of the GNOME doc team, so it
addresses needs that are specific to Linux documentation upstreams and
downstreams.
- The syntax is simpler than docbook, so it should be easier for new
contributors to learn than docbook, but it is still xml-based, so it
can work with translation tools.
- It allows for automatic linking between documents. If I link to a
Thunar document, the bottom of the page of the Thunar document will
automatically contain a link back to the original document.
- If you use Yelp (which I know is dog slow, but I'll get to that) to
display the documentation, all of the linking is done on the fly. So
if all I have is a doc for Xfce's Window Manager and a doc for the
file Manager, Thunar, those docs can work together. If I later add in
a document for Midori or Squeeze, those docs would be integrated into
the doc structure on the fly.  This would accomodate Xfce's modularity
concerns.
- The yelp developer has indicated a willingness to create a "Yelp
library," and Jannis was ok with the dependencies of this.

Downsides:
- The "Yelp library" would not be available for GNOME 2.28, so if we
wanted to go ahead with Mallard docs, we would have to output
everything to HTML in one big document (similar to rST+Sphinx) for
now.  This could be a short-term solution.
- We'd also need to have someone build a help browser around the Yelp
library in C or Vala if we didn't want to use Yelp.
- XML2po is not 100% perfect on the translations at this point, but
it's still pretty good.

As a reference, here's info about Mallard and the Mallard syntax:
Syntax: http://www.gnome.org/~shaunm/mallard/spec.html
10-minute tour: http://www.gnome.org/~shaunm/mallard/tenminutes.html


In short, I don't recommend DITA for a project of Xfce's size. It can
do some powerful stuff if you're handling a lot of documentation, but
it's overkill for a project like Xfce, and I think it would discourage
new people from contributing.

ReStructuredText+Sphinx would be ok if modularity wasn't an issue for
Xfce. Even though translations aren't a big concern with Xfce, it
would also be nice to accommodate them in a manner that's a little
more advanced than copying and pasting.  rST+Sphinx isn't a bad
option, though, and I could support using it for Xfce docs if people
decided that is what is best.

Mallard seems like the best overall compromise to me, though, even if
it isn't fully ready yet.  I've been closely involved with the GNOME
doc team on the project, and they're interested in working to develop
a cross-platform doc solution, and Mallard offers an xml-based syntax
that isn't too complicated. Also, within a year or so, it would be
able to accommodate the modularity of Xfce (something not possible
with rST+Sphinx), and it offers some neat features with regards to
recursive linking.

That's all I have on the subject for now, though.  Please let me know
what you think, and if you have any major concerns or additional
thoughts at this point.  Also, if you feel strongly about one approach
or another, please feel free to share it.  Thanks very much.

Jim