RT3 Documentation: Hackers, FAQ, etc.?

RT Users
1

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 :wink:

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
Resources — Best Practical Solutions, 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

2

Garrett Goebel wrote:
[snip]

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
Resources — Best Practical Solutions, fsck.com/rtfm, and pod
[snip]
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.
[snip]

Mr. Goebels, I write to manifest my agreement. But while writing, I
though that I would look just like one more ranter, and that’s not my
intention (nor is mr. Goebel’s intention, I believe).

I need to solve the same problem that most users have: I need a new
Issue-Tracking system for my company, to replace a home-made one that is
poor, untrustable and badly documented.

And, with that intention, I would volunteer myself to write
documentation for the RT3 system 5-10 hours a week, as long as a
developer or somebody involved with the project volunteer himself for
playing the “mentor” role and guide the documentation effort.

I guess mr Goebels could volunteer himself too, and this will make
10-20 more hours per week in RT3 documentation effort.

Thank you all for the programming effort, for the patience and for
the good open-source software.
Hugs
Luis Campos de Carvalho is BSc in Comp Science,
PerlMonk [SiteDocClan], Cascavel-pm Moderator,
Unix Sys Admin && Certified Oracle DBA
http://www.integral.com.br/

3

And, with that intention, I would volunteer myself to write
documentation for the RT3 system 5-10 hours a week, as long as a
developer or somebody involved with the project volunteer himself for
playing the “mentor” role and guide the documentation effort.

Luis,

Thanks very much for volunteering!  First up, I'd recommend that

you subscribe to rt-doc-workers@lists.fsck.com. There are folks there
who’ve done volunteer RT documentation work over the last several years.
It’s the right place to discuss what aspects of the documenation you’d
like to work on and the best first point of contact for advice about how
to proceed. If there are questions that rt-doc-workers can’t handle,
posting them to rt-devel is the right next step.

We’ve got an as-yet-unannounced RTFM instance on rt3.fsck.com that seph
has been starting to flesh out with content and I’m sure he’d love help.
It’s not at the point where it would be useful to end users, but it’s
getting closer.

One of the things that would probably be most helpful would be trolling
the past few months of rt-users and rt-devel for users’ “HOW-TO”
documents to include in the RTFM instance.

Best,
Jesse

Request Tracker... So much more than a help desk — Best Practical Solutions – Trouble Ticketing. Free.

4

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…

RT is a dead easy install if you follow a few guidelines:

  • follow the directions. When they say “unsupported” understand that to
    mean “there have been problems reported which will result in trouble”.
    Specifically, if you use mod_perl use 1.x instead of 2.x, and do not use
    any perl earlier than 5.8.

(Ok, I ran out of guidelines… That about covers it!)

 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.

Grokking the internals is not necessary if you are just planning on
using it. The interfaces are reasonably clear, it is full-featured,
exceptionally custimizable via gui interfaces, and basically “works out
of the box”. The install directions are perfectly adequate for people
willing to read them.

If you are planning to do development on it, although it is not
documented as well as everyone would like (have you seen ANY product
that is?), the code is modular, well-structured, and straightforward to
understand and modify, once you understand the paradigms used. In fact,
it is designed so that you can replace parts of it with routines of your
own. It is very rare to find a product go to such lengths to make that
possible. In reality, I have found that the RT2 docs do a fair job at
describing it, although there have been significant changes.

 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…

If your window is slipping, go install it and quit talking! :slight_smile:

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.

Many of these issues might have some validity. Maybe you should just
spend 100K on Remedy? Alternatively, consider the situation if you paid
Best Practical 100k for support. (I would argue that the latter is a
better business decision in many cases… If you like, your company can
hire me to tell you that. :slight_smile:

Don’t compare apples and oranges.

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 :wink:

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:

 ...
 
 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.

If your IT org is not accustomed to using high quality open source
software, then yes – you are likely to have a problem selling it.
(Don’t blame RT for that.) If open source is already accepted, stick to
the question of whether it is high quality or not. You won’t have much
of a problem.

Jim Rowan
(Not a Best Practical affiliate!:slight_smile:

5

Jesse Vincent wrote:

Luis Campos de Carvalho wrote:

And, with that intention, I would volunteer myself to
write documentation for the RT3 system 5-10 hours a week,
as long as a developer or somebody involved with the
project volunteer himself for playing the “mentor” role
and guide the documentation effort.

Luis,

Thanks very much for volunteering! First up, I’d recommend
that you subscribe to rt-doc-workers@lists.fsck.com. There are
folks there who’ve done volunteer RT documentation work over
the last several years.

Will do. I’d already checked its archives. It looks to have been dormant
since August. I.e., the automatic looking notification of RTFM changes
appear to have stopped.

[…]

We’ve got an as-yet-unannounced RTFM instance on rt3.fsck.com
that seph has been starting to flesh out with content and I’m
sure he’d love help.

Great. But all I can see is a login screen. And being login-less that leaves
me at an impasse. -I’ll take that question on over to rt-doc-workers…

One of the things that would probably be most helpful would
be trolling the past few months of rt-users and rt-devel for
users’ “HOW-TO” documents to include in the RTFM instance.

Well as I’ll be doing a bit of that anyway, I’ll see what I can do in that
regard.

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

6

Jim Rowan wrote:

Garrett Goebel wrote:

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…

RT is a dead easy install if you follow a few guidelines:

  • follow the directions. When they say “unsupported”
    understand that to mean “there have been problems reported
    which will result in trouble”. Specifically, if you use
    mod_perl use 1.x instead of 2.x, and do not use any perl
    earlier than 5.8.

(Ok, I ran out of guidelines… That about covers it!)

We’ll see. But I’ve read reviews and more than a few posts complaining
otherwise…

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.

Grokking the internals is not necessary if you are just
planning on using it.

Hah! I’d love to just use it. Unfortunately every department has different
needs and even where they don’t, they’ll want to paint the bikeshed a
different color. No… I know whatever we use will be customized
extensively. That’s one of the reasons RT showed up on the radar. It has a
reputation for being developer friendly to change.

The interfaces are reasonably clear, it is full-featured,
exceptionally custimizable via gui interfaces, and basically
“works out of the box”. The install directions are
perfectly adequate for people willing to read them.

That’s fine and good, I just wish schema, api, internals, and customization
howto’s were documented. And I’m sorry, but I’ve scanned the RT3 manual and
it doesn’t really go there. I only have so much time to burn evaluating
stuff…

If you are planning to do development on it, although it
is not documented as well as everyone would like (have you
seen ANY product that is?), the code is modular, well-
structured, and straightforward to understand and modify,
once you understand the paradigms used. In fact, it is
designed so that you can replace parts of it with routines
of your own. It is very rare to find a product go to such
lengths to make that possible. In reality, I have found
that the RT2 docs do a fair job at describing it, although
there have been significant changes.

I have worked with Clientele which is a Customer Relation Management (CRM)
application. And it is well documented and extensible. About as close to an
open source product as I’ve seen from the prospective of providing access to
the change the code. I could modify it to do defect tracking, etc. except
it’d be overkill and costly in per user licensing for simple issue tracking,
defect reporting, etc.

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…

If your window is slipping, go install it and quit talking! :slight_smile:

Indeed.

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.

Many of these issues might have some validity. Maybe you should
just spend 100K on Remedy? Alternatively, consider the situation
if you paid Best Practical 100k for support. (I would argue that
the latter is a better business decision in many cases… If you
like, your company can hire me to tell you that. :slight_smile:

And that I fear is what we’ll do. Lock ourselves into yet another system and
watch it go south. I’m quite certain we’d buy a service contract from Best
Practical. Though probably not on the order of 100k. Though, we’ve certainly
paid more on consultants for proprietary systems that still haven’t produced
results.

If your IT org is not accustomed to using high quality open source
software, then yes – you are likely to have a problem selling it.
(Don’t blame RT for that.) If open source is already accepted,
stick to the question of whether it is high quality or not. You
won’t have much of a problem.

We’re on the cusp of opening new possibilities. Bad impressions formed now,
could have long lasting impact and future adoption of open source solutions.

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

7

We’ve got an as-yet-unannounced RTFM instance on rt3.fsck.com
that seph has been starting to flesh out with content and I’m
sure he’d love help.

Great. But all I can see is a login screen. And being login-less that leaves
me at an impasse. -I’ll take that question on over to rt-doc-workers…

guest/guest will work. We generally don’t hand out accounts with
create/edit abilities until users have contributed a bit to the mailing
lists, etc.

Best,
Jesse

Request Tracker... So much more than a help desk — Best Practical Solutions – Trouble Ticketing. Free.

8

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?

While our software is all publically available, the Business side of the
house can’t be run completely transparently. I can’t yet say anything
detailed about what we’re doing about the documentation effort. At this
point, the "i"s have been dotted, but we’re still waiting on the "t"s
being crossed. When I can tell y’all what’s going on, I will.

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.

RT is an opensource project. It was my hobby for many years before I
quit my day job to concentrate on creating free software. We’re
certainly not a one-man shop, but we are a small company. And as such,
we don’t have a lot of spare time to focus on a slick corporate
branding. We’d much rather spend the time concentrating on creating
world-class software than on making sure that the website has cornflower
blue icons for every resource. Things are much better than they were
six months ago. And six months ago, they were much better than they were
a year ago. I’m confident that they’ll be much improved in another six
months.

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 :wink:

And you’re looking at ditching them. The money they paid to have their
website developed is probably what it would cost me to employ a
competent developer for a year. As the company grows, you will see more
“polish,” but fundamentally, we’re a technology company. And, at the end
of the day, solid technology is what you want and need.

Best,
Jesse Vincent
President
Best Practical Solutions, LLC

Request Tracker... So much more than a help desk — Best Practical Solutions – Trouble Ticketing. Free.