Plans for Xubuntu documentation

[Luzius Thöny]

Jim Campbell wrote:
> Hello All,
>
> As I may have mentioned before, Freddy Martinez and I are giving the 
> Xubuntu
> documentation an overhaul for the Gutsy release.  At the last Xubuntu
> developer meeting we discussed our progress, and as it stands now, we've
> each made local copies of the Ubuntu Feisty documentation, and have been
> modifying the Ubuntu documentation so that it is accurate for Xubuntu.
>
> We are taking this approach because Ubuntu and Xubuntu have so much in
> common, and because we are trying to move to topic-based help, which 
> Ubuntu
> has already implemented.  Working from local copies of the docs has 
> been a
> serviceable way to work so far because we've mostly been familiarizing
> ourselves with docbook, and have not written much new documentation.
>
> However, to help us get started in a more proper direction, and to 
> allow us
> to submit patches for review, we need to be working off of a working 
> copy in
> the repositories.  Because we've been working off of the Ubuntu docs, we
> thought it would be a good idea to have someone copy over the 
> Ubuntu-Feisty
> documentation into the Xubuntu documentation folder in the repository 
> as an
> interim step until the docs become more fleshed out and take on a 
> structure
> that is unique to Xubuntu.  To stay away from file and folder name
> conflicts, perhaps putting a copy of the Ubuntu docs into the following
> path: ~/ubuntu-doc/xubuntu/gutsy. . . would work.
>
> If you all think this is a good idea, could someone please go ahead 
> and move
> a copy of Ubuntu docs over to that location?  Or should I just submit a
> super-huge patch which would accomplish the same task?  :)  If someone 
> has a
> better suggestion, please let us know what you think.  We did discuss 
> other
> alternatives, but this seemed like a reasonable way to start things 
> off so
> that we can begin submitting patches.
>
> Thanks for your help,
>
> Jim

i'm looking forward to xubuntu-docs getting in shape again! i have no 
concerns at all about giving SVN access to jim and freddy.

choosing the right approach for xubuntu-docs is tough. this is because 
multiple sources of information need to be fused together:

1) ubuntu documentation (most of this applies to xubuntu as well)
2) xfce upstream documentation
3) upstream documentation for other apps
4) xubuntu specific information

up till now, the idea has been to basically concentrate on 4). 2) was 
used very rarely (it was outdated at the time, and there's still no 4.4 
documentation, AFAIK), and only selected bits from 1) (some introductory 
stuff about the distro, linux basics, getting on the internet) made it 
into the guide. 3) wasn't used at all, but (where possible) linked to 
from the guide.

the approach you are proposing now is somewhat different, in that you 
want to start with 1), and incorporate 4) and probably 2) (and 3)?) into 
it. i see both an advantage and disadvantage:

+ resulting documentation will be much more complete and coherent 
(one-stop documentation, it's all there in one spot)

- lots of redundancy, resulting in increased maintenance work. if we go 
ahead now and duplicate all docs from ubuntu, and start working on them, 
then we will have to constantly watch all changes on the ubuntu docs and 
merge them over to xubuntu. it's kinda like maintaining a fork, isn't 
it? possible, but not exactly fun :(

the reason why i chose not to work off of ubuntu docs when preparing the 
dapper release was for one laziness (i just didn't feel like maintaing 
many pages that were already well maintainted in ubuntu docs), and for 
the other my intention to avoid redundancy. but i see good reasons for 
both approaches, so i'm fine with it if we want to give it a shot and 
base our gutsy docs off of the ubuntu stuff. so if that's what we want 
to do, i'll try to be there and help.

note: putting the ubuntu docs into a gutsy/ folder below xubuntu/ in the 
repo is not needed, as has been pointed out. if we want to go down that 
road, we'll just write over what's there now in trunk. the current state 
can always be brought back by reverting, and it's also available (and 
buildable) from the feisty branch.

~luzi