Xfce documentation note (kind of long)

[Jim Campbell-9]

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@...
http://foo-projects.org/mailman/listinfo/xfce4-dev

[Christopher Grebs]

Hi Jim,

I just read your notes about sphinx and would like to give you a hint.
Sphinx is able to include various pieces of other sphinx documentation,
either online or offline. I don't know DITA and Mallard that much, but
can they do that as well?

As such, why not just let every software project build it's own
documentation with maybe it's own templates, what ever and include the
documentation sites/pages into one big xfce-docs package.

This then can be rendered to PDF and other output formats as well (very
pleasing).

Just a comment from a along reading people ;)

Regards,
Christopher.

--
GnuPG key ID: 0xC06BCF6C
Key URL: http://webshox.org/~shoxi/Christopher%20Grebs.asc



_______________________________________________
Xfce4-dev mailing list
Xfce4-dev@...
http://foo-projects.org/mailman/listinfo/xfce4-dev

[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@...>:

> 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@...
> http://foo-projects.org/mailman/listinfo/xfce4-dev
>

_______________________________________________
Xfce4-dev mailing list
Xfce4-dev@...
http://foo-projects.org/mailman/listinfo/xfce4-dev

[Brian J. Tarricone-3]

On 2009/06/30 15:00, Mike Massonnet wrote:
> 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.

We have custom m4 macros too.  If ours needs to be improved, feel free
to write patches for xfce4-dev-tools... or at least describe the changes
(in a bug report) so someone else can figure out how to do it best.

        -brian
_______________________________________________
Xfce4-dev mailing list
Xfce4-dev@...
http://foo-projects.org/mailman/listinfo/xfce4-dev

[Mike Massonnet]

2009/7/1 Brian J. Tarricone <brian@...>:

> On 2009/06/30 15:00, Mike Massonnet wrote:
>>
>> 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.
>
> We have custom m4 macros too.  If ours needs to be improved, feel free to
> write patches for xfce4-dev-tools... or at least describe the changes (in a
> bug report) so someone else can figure out how to do it best.

Actually I was wrong by emphasing the use of the m4 macro. I have a
template with all the sub-directories and files and it is just about
copy/pasting it in a new project, just like it is about modifing the
Makefile and create the help directory for GNOME projects.

The real thing is that in GNOME they do not need to add a bunch of
help/fr/Makefile, help/fr/images/Makefile inside the autoconf script.
This is where the build system is less annoying.

But in the end we don't know what the on-coming documentation will look like.

Mike
_______________________________________________
Xfce4-dev mailing list
Xfce4-dev@...
http://foo-projects.org/mailman/listinfo/xfce4-dev

[Brian J. Tarricone-3]

On 2009/06/30 15:44, Mike Massonnet wrote:

> 2009/7/1 Brian J. Tarricone<brian@...>:
>> On 2009/06/30 15:00, Mike Massonnet wrote:
>>> 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.
>> We have custom m4 macros too.  If ours needs to be improved, feel free to
>> write patches for xfce4-dev-tools... or at least describe the changes (in a
>> bug report) so someone else can figure out how to do it best.
>
> Actually I was wrong by emphasing the use of the m4 macro. I have a
> template with all the sub-directories and files and it is just about
> copy/pasting it in a new project, just like it is about modifing the
> Makefile and create the help directory for GNOME projects.
>
> The real thing is that in GNOME they do not need to add a bunch of
> help/fr/Makefile, help/fr/images/Makefile inside the autoconf script.
> This is where the build system is less annoying.

Mmm, yes, I never liked that.  We probably should just store all the
files in the same dir, named $PACKAGE.$LANG.xml, and rename them on
install, maybe with a DOC_LINGUAS file so no one needs to mess with the
makefiles.  But since we're moving to a new docs system it's probably
not worth changing just yet.

        -b
_______________________________________________
Xfce4-dev mailing list
Xfce4-dev@...
http://foo-projects.org/mailman/listinfo/xfce4-dev

[Jannis Pohlmann-3]

On Tue, 30 Jun 2009 22:38:24 +0200
Christopher Grebs <cg@...> wrote:

> Hi Jim,
>
> I just read your notes about sphinx and would like to give you a hint.
> Sphinx is able to include various pieces of other sphinx
> documentation, either online or offline. I don't know DITA and
> Mallard that much, but can they do that as well?

Can you explain how Sphinx does this and what exactly it provides for
scenarios where different components install different documentation
pieces but you still want an overall off- and online documentation
website to be presented to the user?

  - Jannis


_______________________________________________
Xfce4-dev mailing list
Xfce4-dev@...
http://foo-projects.org/mailman/listinfo/xfce4-dev

[Jasper Huijsmans]

Hi Jim,

Thanks for doing that write-up.  It is awesome to see people who are
serious about our documentation.

It just occurred to me that aside from any technical issues, it might
have some advantages for us to choose 'whatever gnome is using'.  Just
as we are using their HIG as a basis for our UI, we could use their
documenation guidelines as well as their documentation system.

Ok, sorry to waste anyones time with my ramblings. I just had an
urgent need to post something Xfce related again after a long time ;-)

You guys are doing great.

Cheers,
        Jasper
_______________________________________________
Xfce4-dev mailing list
Xfce4-dev@...
http://foo-projects.org/mailman/listinfo/xfce4-dev

[Jannis Pohlmann-3]

Hey,

first of all, sorry for replying so late.

On Mon, 29 Jun 2009 14:12:29 -0500
Jim Campbell <jwcampbell@...> wrote:

(snipped the useful overview over the options we have)

> 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.

Yeah, I get that feeling, too. The lack of open source tools for it
definitely is an issue. Also, it seems it's rarely used in open source
projects, hence no GTK+ viewers for it. Or am I wrong? I mean, we could
do pioneer work here, but we really lack the manpower for this.

> 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.

I know that earlier I said we don't care so much about modularity and
we should just have one doc repository. After giving this more thought
I'd like to revoke that. We really want each component to install its
own docs, otherwise we'd violate one of the key concepts of Xfce:
modularity. I mean, we could have one repository and use git submodules
and thelike to include the individual docs in the different tarballs,
but for that the documentation system has support this.

I still think Sphinx isn't capable of that. You have one big reST
tree, you install it and you're done. Doc pages are linked to each
other and stuff. But what if different components contribute separate
documentation parts and you still want them to be linked in some
intelligent way?

Christopher told us Sphinx can do this, but he didn't seem to be able
to elaborate on that more. So for now I assume this kind of scenario is
unsupported.

> 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.

Yes, so far Mallard looks most promising, despite it's early stage. If
it's easy to write a doc viewer on top of a future "libyelp" with
reasonable dependencies, let's do it. Also, Mike tested translating
docbook documentation using .po files and he seemed to be pleased with
this translation workflow, even for longer texts. That clearly speaks
for an XML-based approach that makes it easier for the docs to be
translated.

The question is: do we have any short-term solution? Mallard seems a
bit far away at the moment.
 
> 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.

Thanks again for your investigations, Jim!

  - Jannis


_______________________________________________
Xfce4-dev mailing list
Xfce4-dev@...
http://foo-projects.org/mailman/listinfo/xfce4-dev