Xfce documentation note (kind of long)

[Mike Massonnet]

Hi Jim,

First thanks for the update!

Concerning the translations, we have been positive enough to ditch
xml2po and by this also docbook and prefer a more readable syntax like
ReST. I think that regarding Mallard, it is still an option as the
syntax is meant to be less bloated, but still...

I really can't tell much about xml2po, there isn't a lot of
translators on the documentation and I have no clue what they think
about translating via po-doc. And that reminds me that as someone who
has to add a new translation, the build system definitely sucks. It
sucks less on GNOME, they have a m4 macro to help decrease the code
for automake scripts. Ditching xml2po would make it simpler to add
translations without having to run through endless configure and
makes.

Mike

2009/6/29 Jim Campbell <jwcampbell at ubuntu.com>:
> 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
> _______________________________________________
> Xfce4-dev mailing list
> Xfce4-dev at xfce.org
> http://foo-projects.org/mailman/listinfo/xfce4-dev
>