Xfce Documentation Project

[Nick Schermer]

On Fri, Oct 22, 2010 at 11:11 PM, Robert V. Bolton
<robert at robertvbolton.com> wrote:
> Hello,
>
> My name is Robert V. Bolton and I'm interested in helping with the
> documentation for Xfce. What is the current status of the Xfce documentation
> project?  Just going back trough the Xfce-dev Archives it looks like the
> last discussion of this topic occurred in March of this year.  Has a new
> email list been created just for documentation or is Xfce-dev the best list
> to discuss documentation?

Welcome and thanks for poking this subject again, following a small
status update and how we can continue.

There has been some progress on the generation of the docs in the
various git repositories, but not much documentation has been
improved. The xfce4-docs git repo
(http://git.xfce.org/xfce/xfce4-docs) is basically useless because all
the developers more or less decided they want to keep the
documentation inside their packages.

That said, we obviously still need a lot of documentation updates for
4.8, so suggest the following:

* We empty the xfce4-docs repo and create branches like
<project>-<branch>, for example xfce4-panel-master. Inside the branch
we add the doc files + images + Makefiles.
Right now the documentation translations are also located in this
folder, but we can move those to handle all the translations in the
(for example) xfce4-panel modules or in xfce4-docs (transifex commits
in xfce4-docs).
I think the latter is somewhat better since then translators always
see the latest docs changes, this also means one xfce4-docs module in
transifex with multiple components for each project, projects can use
those components in releases for a better overview... ok... OT.

* A "documentation-tools" branch for scripts doc writers can install
on their system to update po files, validate stuff, build
mallard/docbook html to viewing the result. Might also be useful for
translations since I've seen a lot of translations that result in
invalid xml when merging with xml2po.

* The master branch and (eventually the xfce-4.x branches) for the
xfce users guide, which means moving this out of xfce-utils[1]. We can
release this as a new module for the global xfce documentation.

* With the setup above we can work with git submodules[2], so
developers can pull the latest docs from the xfce4-docs repo whenever
they want and people working on documentation cannot touch the source
code in core.

* Setup git access for Robert, Jim, the core devs and all the people
out there to work in the documentation.

All in all not very complicated I'd say, so other core developers,
Robert, Jim and others? Good idea or do I miss something obvious? If
people agree I can set this up.

Nick

[1] I'd love to get rid if this module some day. Xfrun can be migrated
in xfce4-appfinder (on my 4.10 TODO list) and the other scripts can
move in more suitable places or are already obsolete. However not
suitable for discussing this right now.

[2] Submodules can only work with branches (well a pointer to a
commit), not cd into a directory inside a tree.