Wiki documentation

[Brian J. Tarricone]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 1/18/2006 4:25 PM, Andrew Conkling wrote:
> On 1/18/06, Brian J. Tarricone <bjt23 at cornell.edu> wrote:
>> On 1/18/2006 1:57 PM, Andrew Conkling wrote:
>>
>>> I'd really be interested in figuring out a good way to get the
>>> official docs wiki-fied
>> I don't really see how this is a positive step.  How is this better than
>> including the docs in docbook format with the packages themselves?  The
>> only place the documentation is really lacking, IMHO, is in the
>> development tree, which will be fixed up before 4.4 (same as what
>> happened for 4.1->4.2).
>>
>> Would this mean ditching the documentation supplied with the package
>> that gets installed to the user's HD?  If so, I'm firmly against this.
>> If not, how do we keep the two in sync?
> 
> I don't think this should replace the provided documentation.  I don't
> even really think any content needs to be changed on it to be helpful.
>  I'm really more interested in linking everything up so that niche
> things that everyone seems to know after a while can be provided and
> in (ultimately) making the wiki into a good resource for new users;
> the forums and mailing lists see a lot of duplicated questions and
> such.  Auke's efforts in making a mailing list FAQ are great. 
> (They're actually what's inspired me to make something a bit more
> central.  I started something on the forum but found it to be unwieldy
> so when I lost it, it was very easy to give it up.

What's wrong with just a link on the wiki to http://xfce.org/documentation/?

> However, that brings up an interesting point: what if we put the
> documentation on the wiki and changes are made to it?  I suppose we
> could monitor them to make sure they're positive and clear, but that
> has the potential to provide more and better documentation (not to say
> anything bad about it currently) that could be provided with future
> versions of the docs with the packages.

Perhaps, but this is more work that someone has to assume responsibility
for.  Personally I don't want to merge doc changes from a wiki into
docbook.  That sounds like a waste of time for me, so I'm not going to
do it, in favor of updating my docs myself as I see a need to.  If
someone wants to help update the documentation, the docbook source --
which is very readable and easy to edit -- is available from SVN, and
patches are always welcome.  We could even include direct links do the
docbook source in some kind of "how to contribute" section.

> I'm jus' sayin', ya know?  I'm not really wiki-crazy, but they do seem
> like a pretty good resource when done well.

Sure they are, for some applications.  I just don't think this is one of
them, but I'm probably biased as I generally dislike wikis.

	-brian


-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (MingW32)

iD8DBQFDzuiO6XyW6VEeAnsRAgu7AJ0QbcLxd5xGfr7+mfZbJdtqLkw1fwCdFGGF
uYHcDuWJgfi4/KpQwEDtsvU=
=gftq
-----END PGP SIGNATURE-----