4.4 Documentation

[Brian J. Tarricone]

On Tue, 08 May 2007 13:53:22 -0700 Josh Saddler wrote:

>Hello. I'm Josh, and I'm a documentation developer for Gentoo Linux (I
>just finished up the handbooks and related docs for our new 2007.0
>release). Been using Xfce since 4.2 and the exciting 4.3.99 days as
>well; I love it! Anyway, as part of that love and appreciation, I think
>it's time that I contribute something to Xfce. Writing a guide for the
>distribution side of running Xfce is one thing
>(http://www.gentoo.org/doc/en/xfce-config.xml), but I'd like to help
>out with the upstream docs.

Sounds great to me.  Unfortunately in Xfce-land, the docs tend to get
updated hastily and (IMHO, somewhat poorly) right before we do
releases, and so the quality and completeness is very variable.

>Specifically, some online 4.4 documentation. I see the existing 4.2
>usage manual and the 4.4 guided tour (both fantastic works in and of
>themselves), but I do notice a great big 4.4-shaped hole that I'd like
>to fill.

My understanding is that the per-module docs are more or less done, but
they just haven't been collated and actually uplaoded the website.  I'm
not sure what the status of the user guide is.

>I spoke with Jasper, and he showed me where the XML source files are;
>excellent. We work exclusively with XML over in Gentoo, so this is
>familiar territory. Only difference is that we keep separate CVS repos
>for our online documentation; centralized vs. decentralized
>(http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/).

I think we've talked about how we store our docs several times, but
never really came to any kind of consensus as to whether we should
change or not.  So, status quo...

>Anyway, my goal is to create a usage guide for 4.4 similar to the one
>for 4.2 online. That's the most obvious area that needs improvement to
>me, but what else is needed? Any updates/editing/better English needed
>elsewhere?

The docs for all modules can always use polishing.  Most Xfce module
maintainers aren't native English speakers, so proofreading would be
very helpful.  Otherwise, I think many of the modules haven't been
completely updated for 4.4, which obviously needs to be done.

>An updated usage manual is the most useful doc to do first, in my view.
>What other areas of the documentation need attention? Things I've
>missed? My other question to the developers and users is: what kind of
>documentation would *you* like to see? Anyone else been planning
>something similar? I'd like to work with you guys rather than reinvent
>the wheel or waste hours duplicating previous work, though if that's
>necessary, then that's what I'll do. :)

Well, AFAIK, the only documentation we have is what you see on the
website, plus the per-module documentation in the 'doc' or 'docs'
directories, much of which is incomplete.  Aside from updating and
polishing all that, anything else that you think would be useful to the
Xfce user community would be helpful.

	-brian