[rt-users] RT3 Documentation: Hackers, FAQ, etc. ???

[Garrett Goebel]

A couple days ago, Daniel A. Melo asked about the missing RT3 Hacking
Guide... But his post has apparently been warnocked. There are other posts
requesting RT3 internals documentation from Patrick LeBoutillier and Mikhail
Sobolev dating back to June and September... which also went unanswered.

In early November, Bob Goldstein asked about meta-docs
(http://lists.fsck.com/pipermail/rt-users/2003-November/018157.html).
Specifically he asked about the missing RT3 FAQ and Hacking Guide. Jesse
responded:

> *nod* Point well taken. The documentation effort is somewhat
> behind where we'd like it to be, though we should have
> exciting news on that front soon.


When is soon?
Who is we?
Will you be wanting feedback?
How to contribute?


Our company is looking to transition away from our current issue tracking
system. I've been hesitant to evaluate RT because of its reputation for a
difficult install and configuration... That and lack of developer
documentation for the current release. I have the time to do a vanilla
install, but not necessarily to wade in and grok the code. However, a
vanilla install isn't going to give me an overview of the schema, internals,
extensibility, etc. I.e., what we as a customer would have to look forward
to and live with if the vanilla install looks promising. 

Currently, I'm left to read the RT2 developer docs and hope RT3 is only
different in "better" ways. The window of opportunity at my company is slip
sliding away. I guess I'll go ahead and see how far I get... 

Even if the IS guys like the demo... And I don't mean to be an ass here, but
I can foresee the objections I can expect to get. They're going to visit the
bestpractical website and see less documentation than they're used to and no
convenient access to a knowledgebook. If they're patient enough to navigate
the website, they'll eventually find more documentation on fsck.com/rtfm.
But the click paths between sites aren't always short, consistent or
obvious. Then perhaps they'll visit the fsck.com homepage itself, and the
impression that will be formed when they realize how intertwined the company
and Jesse's personal website are, will be of a one-man shop operating on a
shoe-string.

Of course the product (with support contract) that we're currently using has
bad documentation, is bug-ridden and has provided almost nothing in the way
of paid for support. But they sure do have slick website ;)

At least RT is open source and looks fairly mature. Though if it is within
Best Practical's game plan to make in-roads into your typical
blinders-half-on mostly microsoft company, here are a couple of suggestions:

o  More documentation: schema, internals, customization, 3rd party add-ons

o  Better documentation: continuous updates and improvements driven by
developer community participation

o  Centralized documentation: currently split between
bestpractical.com/rt/docs.html, fsck.com/rtfm, and pod

o  Streamline the site for the return visitors. People will visit the site
once to read the product literature. But those who use the product and visit
the site frequently will be primarily interested in: recent news,
downloading updates/patches/add-ons, looking up answers to problems, and
documentation. One pain for example: it currently takes ~6 clicks to get to
the mailing list archives

o  Put a better chinese wall between the personal and company websites.
Consider recasting fsck.com or creating an explicitly Best Practical
endorsed developer community site. In which case you could leave the company
website as sales brochure, but more quickly shunt the developers to the
developer site and provide the frequent use items I'd mentioned there.


Sorry for the rant... I'm just worried about the hard sell I'll have if I
take a fancy to RT and want to push it. And I have to say, RT looks
promising. I have the impression that the people who swear by it out number
those who swear at it. 

cheers,

Garrett

--
Garrett Goebel
IS Development Specialist 

ScriptPro                   Direct: 913.403.5261 
5828 Reeds Road               Main: 913.384.1008 
Mission, KS 66202              Fax: 913.384.2180 
www.scriptpro.com          garrett at scriptpro dot com 
 
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.bestpractical.com/pipermail/rt-users/attachments/20031203/9c04c9b9/attachment.htm>