Stephen,
Here are the help files I use the most:
1) Coldfusion help integrated into Homesite - easily extensible, context
sensitive and easy to navigate. The downside is that it's integrated into 1
product, so if I'm using eclipse or (gulp) dreamweaver I don't get all the
advantages.
2) MS SQL 2000 Books online for - Not integrated into anything (stands
alone), quickly searchable. Its in the CHM format. I frankly and unabashadly
think this is the best help file ever written. Nothing I've seen from mySQL
or Oracle even comes close to it. There is a good division between "syntax
description" (as in looking up "JOIN" or "SELECT") and tutorial like
description (as in "tell me how to..."). I can generally find an answer to
my problem without feeling like I'm searching at all.
3) MM (or Adobe) help for flash, DW, Flex etc. - these are help files that
come in those little horrid flash-like windows with the sliding pain. I have
never discovered what they were thinking when they organized this help. It
generally does not have examples that are helpful to me unless I want to do
something "really neat" like drag something around or make a smiley. If I
just want to style a text box or programatically populate a set of radio
buttons or soemthing it's a guaranteed 2 hours of my life I'll never get
back.
Of course I think I dig into an ad-hoc help file or two every day in the
course of working. Most of them are really terrible. I also suppose that it
takes a lot of time and effort to create a good one. Most programmers are
not writers or trainers... so I guess I can give them a pass. Still, I would
collaborate on someone regarding the help if we can agree upon a structure
and divide up the writing. The big issue with a small, fast moving project
like FC is that the documentation is always outstripped by the version
advancing to the next level.
-Mark
_____
From: [email protected] [mailto:[EMAIL PROTECTED] On
Behalf Of Stephen Moretti
Sent: Wednesday, January 03, 2007 4:43 AM
To: [email protected]
Subject: [farcry-dev] Re: is Wiki down?
On 02/01/07, Mark A Kruger <[EMAIL PROTECTED]> wrote:
Stephen,
Excuse me if this is out of place .... but I'm not convinced the the wiki is
the best form of documentation. I would like to see a more formal help that
included everything. As it is the wiki includes things developers run into
that they think need documenting. What is really needed is a book :)
Yeah I'm not sold on the whole wiki business in general and not just for
farcry. Its great as a starting point and if you have the time to put into
managing it, but generally they seem to end up a bit half done and randomly
organised.
Farcry definitely would benefit from a decent set of docs, whether thats a
book... I'm not sure...
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"farcry-dev" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/farcry-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
