Poor Applictaion Documentation

[Matthew Seaman]

On Sun, Nov 14, 2004 at 05:14:39PM +0000, Danny Browne wrote:
> More of a general gripe thatn a question,
> 
> Why are most of the ports for BSD soooo poorly documented. This is somethig i was very suprised at.

This isn't the fault of the FreeBSD project: the ports system can only
provide basically what the software authors make available.  If it was
a requirement that software should be documented to around the same
standard as FreeBSD itself before it could be made into a port, then
there would be only a fraction of the software currently available in
the ports.
 
> I am not looking in the right places?
> 
> For example, try and find some page on the web that will tell what the latest version of gnome fifth toe, (or power tools or whatever) is and what aditional packages it will install. Its impossible, because it's not documented. 

Part of the problem is just that: I suspect that you simply aren't
looking in quite the right places -- and it's not like there's any
sort of standard for how projects should be documented, or how
technical discussions should be operated.  Maybe there's a Wiki.  Or
an ordinary website.  Or a mailing list. Or a Usenet group.

Or perhaps it's just that there is very little documentation
available.  It's fairly typical behaviour to write the code, release
it generally for testing and so forth, and only worry about
documentation at a very late stage.

One of the advantages of the FreeBSD ports system is that ports have
maintainers, and those maintainers should be keeping up with the
mailing lists or whatever, and will update their ports very promptly.
That makes the ports system a pretty good central location for keeping
up to date with new software versions -- especially if you use
http://www.freshports.org/.  That site will also tell you just about
anything you could need to know about any port, including what all of
its dependencies are.
 
> And it's not just gnome alot of the open source UNIX/GNU Linux  applications websites are poorly maintained and info is quite often seriously outdated.
> 
> Feel free to bitch at me if i'm wrong here, but as a relatively new user this has been my biggest problem. Not the techincal side.

Well, that I'm afraid, is just the way of the world.  What you're
talking about is for the most part written by volunteers, often in
their spare time.  If you think that documentation is lacking, then
you could volunteer to help.  Most projects are glad of all of the
help they can get.

	Cheers,

	Matthew

-- 
Dr Matthew J Seaman MA, D.Phil.                       26 The Paddocks
                                                      Savill Way
PGP: http://www.infracaninophile.co.uk/pgpkey         Marlow
Tel: +44 1628 476614                                  Bucks., SL7 1TH UK
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
Url : http://lists.freebsd.org/pipermail/freebsd-questions/attachments/20041114/6309f778/attachment.bin