Board index » jbuilder » Do you have trouble with JBuilder Help?

Do you have trouble with JBuilder Help?


2004-01-15 12:38:07 PM
jbuilder10
Hi -
We're working on making JBuilder's documentation easier for programmers to
use. There will be postings on other specific issues later on. Presently,
we're looking for feedback on the Index in the Help viewer.
Next time you have trouble finding something, please tell us what term you
used for the search. Please include your misspellings, if any (seriously, I
mean it.) Post your findings on the borland.public.jbuilder.documentation
newsgroup or email them to XXXX@XXXXX.COM .
We have some theories about what patterns to use to improve our index, but
need a) validation and b) more data. "Laundry lists" of attempted search
terms from a variety of users will allow us to extrapolate better language
patterns to use when writing index entries. Input from programmers for whom
English is a second language but who use JBuilder in English is also
important.
Any other feedback or suggestions for improving the documentation (the more
specific, the better) will be very welcome.
Many thanks,
Isabel
 
 

Re:Do you have trouble with JBuilder Help?

"Isabel Tifft" < XXXX@XXXXX.COM >wrote in message
Quote
We're working on making JBuilder's documentation easier for
programmers to
use. There will be postings on other specific issues later on.
Presently,
we're looking for feedback on the Index in the Help viewer.
To be honest, I never use the Index tab and can't think of any reason
why I would. The way I see it, the Index is little more than a poor
man's Find tab where I can only search for terms that someone else
thought of ahead of time. I guess the index lets you enter synonyms and
other words that wouldn't come up in an actual text search of the
documentation, but I can usually think of those myself and try them in
the Find tab. And that could just as easily be handled by adding a
"Keywords" line to the end of the documentation, so those words would
appear as hits in a search.
Quote
Any other feedback or suggestions for improving the documentation (the
more
specific, the better) will be very welcome.
One thing I'd like to see is more direct links from errors to their
solutions.
For example, if I compile my code and get the error, "Foo.java: cannot
resolve symbol: method printyln (jhava.lang.String) in class
java.io.PrintStream at line ...," I'd like a help dialog that tells me
likely causes of that error (ex. I spelled the method name incorrectly).
I can hit F1 on the error message, but that page tells me nothing about
that error and almost nothing about anything.
If I get an error about java.lang.Object not being found, I should be
shown a link to information about correcting my JDK configuration.
If I switch to the Design view and get a "Red Bean" error, I'd like a
link that takes me to the release notes and tells me why that happened
and how I can fix it.
Some of this documentation already exists, but it could be better and/or
easier to find. I'm basically thinking of FAQ type issues (tech.
support could probably give you a list of dozens :-) that could be
resolved by a little more hand-holding.
--
Gillmer J. Derge (TeamB)
 

Re:Do you have trouble with JBuilder Help?

Gillmer J. Derge (TeamB) wrote:
Quote
"Isabel Tifft" < XXXX@XXXXX.COM >wrote in message
news:40061931$ XXXX@XXXXX.COM ...
>We're working on making JBuilder's documentation easier for
programmers to
>use. There will be postings on other specific issues later on.
Presently,
>we're looking for feedback on the Index in the Help viewer.

I would pretty much agree with Gilmer. I do not desire to see the index tabs
go away, but a good FAQ resource would be invaluable. It would help cut
down on these repeatitive questions we get in the NGs.
 

{smallsort}

Re:Do you have trouble with JBuilder Help?

It would help cut
Quote
down on these repeatitive questions we get in the NGs.
We are researching what would take to surface "how do I" documentation,
quick-and-dirty procedural steps to accomplish common tasks. Do think that
would fill the need you see for FAQ-type material?
You guys make good points, but raise a deeper issue: making something usable
doesn't mean it will be used. Many use the newsgroups (or developer
support, if they have contracts) _instead_ of the documentation -- as you
are probably well aware, RTFM is a comment made all too often in Dev
Support's notes.
I believe most frequently asked questions are answered in the documentation.
(If you know of gaps, please please please let me know.) If we create an
index that uses sufficiently meaningful search strings, all answers will be
accessible. This doesn't mean that newsgroup junkies would _use_ the Index,
however. Like Gillmer, they may never even look at it.
Our usability studies have shown that, despite the common contemptuous
remarks about never using help, significant numbers do use the documentation
and do have specific expectations and needs. These are not necessarily the
same people who are often on the newsgroups. Personally, I feel like I'm
shooting in the dark here, but every bit of info helps.
Regards,
Isabel
 

Re:Do you have trouble with JBuilder Help?

"Isabel Tifft" < XXXX@XXXXX.COM >wrote in message
Quote
You guys make good points, but raise a deeper issue: making something
usable
doesn't mean it will be used. Many use the newsgroups (or developer
support, if they have contracts) _instead_ of the documentation -- as
you
are probably well aware, RTFM is a comment made all too often in Dev
Support's notes.
That's true, but I see that as a separate problem and unfortunately not
one that it's in our power to solve. :-)
Quote
I believe most frequently asked questions are answered in the
documentation.
(If you know of gaps, please please please let me know.) If we create
an
index that uses sufficiently meaningful search strings, all answers
will be
accessible.
Many are documented in places where nobody could ever find them without
already knowing where to look. Like you say, the key thing is making
sure people can find the answers. Some examples:
* ATI video problems: If you know that you should read the comments in
bin/jdk.config, then yes this is documented, but if you're looking in
the help files then you aren't going to find it.
* Red Beans: If you know that you should look in the release notes for
the term "red beans" then yes this is documented, but if you're looking
in the help files and/or searching based on the error message you
recieve then you aren't going to find it.
* "Q: Why can't my project find my class / how do I put my jar file on
my project's classpath? A: Define a library." If you know that you need
to look for documentation on "libraries" then yes this is documented,
but if you know that then you don't have the problem, and if you don't
know that then you aren't going to find it.
Ultimately I think it comes down to indexing based on the problem and/or
symptoms rather than the solution.
Quote
Our usability studies have shown that, despite the common contemptuous
remarks about never using help, significant numbers do use the
documentation
This reminds me of another example. A very common JBuilder Foundation
issue is "Where's the documentation?" Answer: you didn't download it.
Again, this is a case where the error message could be made to lead much
more directly to the solution.
--
Gillmer J. Derge (TeamB)
 

Re:Do you have trouble with JBuilder Help?

"Gillmer J. Derge (TeamB)" < XXXX@XXXXX.COM >wrote in message
Quote
Ultimately I think it comes down to indexing based on the problem
and/or
symptoms rather than the solution.
It occurs to me that this may be ambiguous. I mean that indexing based
on the problem would be a good thing.
--
Gillmer J. Derge (TeamB)
 

Re:Do you have trouble with JBuilder Help?

Isabel Tifft wrote:
Quote
We're working on making JBuilder's documentation easier for programmers to
use.
From an Open Tool document writer's perspective,
it would be nice to have several things made
easier to:
1. Integrate custom help into the JBuilder Help
system. I believe that Eclipse at least makes this
feasible, if not easy. Some plug-ins that I've
played with have somehow inserted their help documents
into the Eclipse help system.
2. Somehow cross-reference topics in
JBuilder's main help from an Open Tool's help.
By this I mean that if my Open Tool help wants to
<a href>to something in JBuilder Help, things are
a bit awkward and iffy -- quite dependent on the
installation location of JBuilder. Or have I overlooked
something?
--
Paul Furbacher (TeamB)
Save time, search the archives:
www.borland.com/newsgroups/ngsearch.html
Is it in Joi Ellis's Faq-O-Matic?
www.visi.com/~gyles19/fom-serve/cache/1.html
Finally, please send responses to the newsgroup only.
That means, do not send email directly to me.
Thank you.
 

Re:Do you have trouble with JBuilder Help?

Excellent suggestions/points, Gillmer. Thank you. I'll take these up with
the doc team.
Isabel
 

Re:Do you have trouble with JBuilder Help?

Paul,
We're working on #1 (I suppose I shouldn't say that as it's a
"forward-looking statement", but we live in the real world) and I'll have to
look into #2. Thank you for the suggestions.
Isabel
 

Re:Do you have trouble with JBuilder Help?

Isabel Tifft wrote:
Quote
Hi -

We're working on making JBuilder's documentation easier for programmers to
use. There will be postings on other specific issues later on. Presently,
we're looking for feedback on the Index in the Help viewer.

Next time you have trouble finding something, please tell us what term you
used for the search. Please include your misspellings, if any (seriously, I
mean it.) Post your findings on the borland.public.jbuilder.documentation
newsgroup or email them to XXXX@XXXXX.COM .

We have some theories about what patterns to use to improve our index, but
need a) validation and b) more data. "Laundry lists" of attempted search
terms from a variety of users will allow us to extrapolate better language
patterns to use when writing index entries. Input from programmers for whom
English is a second language but who use JBuilder in English is also
important.

Any other feedback or suggestions for improving the documentation (the more
specific, the better) will be very welcome.

Many thanks,
Isabel


I'm probably asking for too much here, but...
It would be nice to have a more "proactive" help system. I hate to
admit it, but one thing (ok, maybe the only thing) I like about Visual
Studio .NET is the nice little context sensitive Help panel, that
contains a list of hyperlinks to Help file items that are relevant to
what you are currently working on.
--
Regards,
Lori Olson (TeamB)
------------
Save yourself, and everyone else, some time and search the
newsgroups and the FAQ-O-Matic before posting your next
question.
Google Advanced Newsgroup Search
www.google.ca/advanced_group_search
Other Newsgroup Searches:
www.borland.com/newsgroups/ngsearch.html
Joi Ellis's FAQ-O-Matic:
www.visi.com/~gyles19/fom-serve/cache/1.html
 

Re:Do you have trouble with JBuilder Help?

Interesting. Thanks. Someone in-house had mentioned this; looks like I
need to get a copy of Visual Studio.NET. :)
Isabel
"Lori M Olson (TeamB)" < XXXX@XXXXX.COM >wrote in message
Quote
Isabel Tifft wrote:

>Hi -
>
>We're working on making JBuilder's documentation easier for programmers
to
>use. There will be postings on other specific issues later on.
Presently,
>we're looking for feedback on the Index in the Help viewer.
>
>Next time you have trouble finding something, please tell us what term
you
>used for the search. Please include your misspellings, if any
(seriously, I
>mean it.) Post your findings on the
borland.public.jbuilder.documentation
>newsgroup or email them to XXXX@XXXXX.COM .
>
>We have some theories about what patterns to use to improve our index,
but
>need a) validation and b) more data. "Laundry lists" of attempted search
>terms from a variety of users will allow us to extrapolate better
language
>patterns to use when writing index entries. Input from programmers for
whom
>English is a second language but who use JBuilder in English is also
>important.
>
>Any other feedback or suggestions for improving the documentation (the
more
>specific, the better) will be very welcome.
>
>Many thanks,
>Isabel
>
>

I'm probably asking for too much here, but...

It would be nice to have a more "proactive" help system. I hate to
admit it, but one thing (ok, maybe the only thing) I like about Visual
Studio .NET is the nice little context sensitive Help panel, that
contains a list of hyperlinks to Help file items that are relevant to
what you are currently working on.

--

Regards,

Lori Olson (TeamB)

------------

Save yourself, and everyone else, some time and search the
newsgroups and the FAQ-O-Matic before posting your next
question.

Google Advanced Newsgroup Search
www.google.ca/advanced_group_search
Other Newsgroup Searches:
www.borland.com/newsgroups/ngsearch.html
Joi Ellis's FAQ-O-Matic:
www.visi.com/~gyles19/fom-serve/cache/1.html