Documentation Response...

Gentleman:

Where is "suitable" being used? As an American, seems like a perfectly good
English word to me....

Some of you feel that the documentation is lacking -- can you please be more
specific as to what you'd like to see? We have many different skill level
users using IDEA, and we try to accommodate everyone; however, if we don't
have specific feedback, then we don't know what documentation to prioritize.
There will be a "Quick Start" guide coming out soon, and this will address
many of the basic features to get you up and going. But, what specific
would you like to see.

As for misspellings -- it happens. Please, when you say "there are
misspellings," can you please tell us WHERE, so we can fix them?

And finally, if you have any questions, concerns, or complaints about
documentation, please post them in: jetbrains.intellij.documentation -- this
is why we have it.




"Michael Jouravlev" <mikus@mail.ru> wrote in message
news:atnqcp$j8c$1@is.intellij.net...

"charles decroes" <intellij@decroes.com> wrote in
message news:7213329.1039721107662.JavaMail.jrun@is.intellij.net...
I am looking for a complete document on all the features of IntelliJ. I

am tired of

stumbling upon these features and thinking "wow i could have used this

last week".

I have read the overview but it seems like the help document is really

the in-depth

coverage I am looking for. Does anyone know where I can get a pdf or

some

printable

version of it? Is there any other documents that you would suggest

reading? I know

I can read the help online, and even print each individual page but I

would rather print

the entire thing and work through it like a book.

>

The situation is even worse: help file is not complete and has a lot of
misspellings and sometimes just bad english ("suitable" is not english and
barely an american english). I am not saying that my english is perfect,

but

I can see errors in the others' documents. I did not read the whole help
file, but here is one example: intentions. "Editing files/Indended

Actions"

does not describe how to turn intention back on. The list of intentions is
incomplete.

>

As a general help file drawback: the search option within the help page
(ctrl-f or something) is unavailable, so for example I cannot locate

needed

intention in the intention list.

>

The help text is written in a slow book manner ("when you have a lot of
code, mistakes are unavoidable..."). Hey, this is not a book which I read
over the dinner, this is an online help file! I know that I make mistakes.

I

know that IDEA can assist. I know "for instance". Make it short, clean,

and

complete. Mean business!

>

Here is how I would rewrite the aforementioned section about intentions

(not

polished, but gives the idea):

>

*******
Intention Action inline code wizard helps to maintain:

  • the uniform code style;

  • adherence to Java language, J2EE, corporate and personal coding

standards;

  • code consistency throughout the project

>

Intention Action is visually identified in a source code pane as a yellow
("turned on") light bulb on the left margin of the code pane. Intention
Action light bulb is displayed when caret is positioned on the suspicious
token.

>

To open the Intention Actions list:

  • mouse over the light bulb and open Intention Action drop-down menu

from

the Inline Wizard window (To the readers: "Inline Wizard window" or
"Autocorrect window" or "Smartedit toolbox" should be defined in editor
cotrols' description in the other part of help file. Also, bullets for "do
this AND then this AND then this" and for "do this OR this" should be
visually different).
- OR -

  • press Alt-Enter

>

To apply the Intention select appropriate action from the Intention Action
list.

>

To turn the particular Intention Action rule off click on the lightbulb on
the left of the rule. The lighbulb becomes gray ("turned off").

>

To turn on the intention press ...

>

To turn off all Intention Actions press ...

>

And so on.

>

Cheers,
Michael J.

>
>
>


5 comments
Comment actions Permalink

David J. Stennett wrote:

As for misspellings -- it happens. Please, when you say "there are
misspellings," can you please tell us WHERE, so we can fix them?


Just as an example, I pointed out the following misspellings in
http://www.intellij.net/tracker/idea/viewSCR?publicId=8190:

Hierachy, procces, surronding, immplemented, implementaion, enternames,
wil, occured, runninig, nota, opeartion, exisiting, seetings, VIews,
beggining, ovewritten, specifiy, entires, Deafault, avalable, occurence,
bundeled, Maximim, reusethe, debugget, detectes, supeclass, Memebers,
refatoring, incompilable (uncompilable), qualificators (qualifiers? or
what?), Applyng, ha ve, initilization, overriden, jav.lang, upcasted
(shouldn't this be "upcast"?), methos, helpfull, heterogenous,
infrastucture, servies, approriate, refere.

These are over 40 misspellings that would have been caught by a spell
checker.

0
Comment actions Permalink


"David J. Stennett" <david@intellij.com> wrote in message
news:atq2v1$o32$1@is.intellij.net...

Where is "suitable" being used? As an American, seems like a perfectly

good

English word to me....


OK, I had to know better that this remark would cause strong feedback :)
Sorry for that. It was just something I was taught long ago that "suitable"
suits :) better when talking about clothes and stuff, not about some
abstract matters. Anyway, I retract this remark :)

Some of you feel that the documentation is lacking -- can you please be

more

specific as to what you'd like to see?


How about the example of help page that I posted? I did not see your
reaction on it. Short but full. No long beginnings, just the meat. And all
interface elements should be described separately and fully (not all of them
are described in "IDEA User Interface", like Intention Acion bulb and box.
Do you have a name for this box? How about "Inline Wizard"? ;) ), as well
as help file conventions ("How to use this help").

We have many different skill level
users using IDEA, and we try to accommodate everyone;


Help file is a reference, not a novel. IMHO it should describe how and
when particular tools should be used. Examples are welcome (separately). To
help novice users you may write the whole new "Getting started with IDEA"
part.

There will be a "Quick Start" guide coming out soon, and this will address
many of the basic features to get you up and going.


What I said did not mean that some features should be left behind the
curtain because they are "for advanced users" or because they "for beginners
and every advanced user knows about it". When I talk about short help file
pages I mean that they are also complete.

I truly believe that one can create documentation that is short, concise and
full, and that could be used by both advanced users and novice users. I want
to repeat again: online help file is not a novel :)))

And now, if you really interested in this discussion, I want to take apart
the page about Intention Actions. It may look like I really got hung up on
it ;)

"When you have lot of code, mistakes are unavoidable." -


completely
redundant phrase.
"IDEA can assist you in dealing with them by trying to guess what you were
going to make or what you INTENDED to do. In such the cases IDEA will prompt
you with one or more ways of solving a problem. You can agree with the
proposed solution or correct the problem by yourself. In other words, if the
IDE considers that there is something wrong with your code IDEA will suggest
an ACTION to fix it which is called an Intention Action." -


too long, too
bookish. People do not have time to read this stuff. They need to know what
Intention Action is for and how it can be used. How exactly IDEA can assist?
How exactly it knows that "something wrong with the code"? Where are the
rules defined? Are they configurable? Also, what is ACTION which is
suggested? No definition in the help file for this. Why it is uppercase, I
hear you!

"For instance, writing code you see you need a new field. You can act in a
traditional manner, create a new field and start using it. Or you can do it
otherwise: use this new field first, and then place the caret on the field
usage. IDEA will show a bulb sign." -


The only meaninful information in
this piece is that bulb appears when caret is placed on the field.

"And if you press Alt + Enter or click the bulb IDEA will show what it can
suggest for this reference." -


I would prefer "To ...", not "If ...".

"In this case you can create a field, a local variable or rename a
reference. Select a suitable solution (in this case - creating a field) and
press Enter. IDEA will make a new field and will try to guess its type. Or,
if none of the suggested solutions is applicable, you can press
Escape." -


Not "in this case", but "in the example shown". And again, not
"Or, if...", but "To reject the suggested actions press Esc" or something
like this.

There are intention actions that appears for a correct code (that is, with
no errors/warnings) suggesting useful or optimizing changes. -


This is
redundant.

"To see the complete list of Intention Actions, please, refer to the
Intention Action List section." -


This is perfect.

"If you needn't an intention action to appear for a particular expression or
statement each time the caret is on it you can switch it off. Every
suggested intention action has a bulb sign to the left. Just click it. The
bulb sign will be grayed and this action will not appear again. However, if
there are several actions possible you have to switch off all of them." -


Too long again. I would prefer: "To turn off an Intention Action click on
the lightbulb to the left of action description".

"And if you wish to see what intention actions are available for this
expression or statement you can still use the Alt + Enter shortcut. To
switch on the disabled intention action click the grayed bulb." -


I am
not goiing to argue about usability of this approach... And how to turn it
off/on using keyboard? Right, use spacebar. Nothing about it.

"There is a specific type of intention action for a case when you use a
class that should be imported. After IDEA determined that the typed class is
to be imported you will see the popup window suggesting to do it." -


Here
we go! Here is another Inline Code Wizard. This should be incorporated in
"normal" Actions.

So, we need to define the box and a bulb somewhere. Microsoft call it... I
do not remember. SmartEdit? Autocorrect box? Whatever. You can define this
control as "Inline code wizard" somewhere in the "IDEA user interface":

===
Inline code wizard pops up when an automated action is possible. Inline code
wizard is represented in the code editor by an Indicator or an Indicator
Minibox and is shown at the beginning of the line. Indicator notifies that
automated action is possible. When Indicator moused over it changes to
Indicator Minibox. Indicator Minibox allows to select the action from the
list.

The following types of inline code wizards are available:

  • Intention Action. Indicator is a yellow ("turned on") light bulb.

  • Import Action. Indicator is a blue question mark.

  • bla-bla-bla Action -- Indicator is a big brown bird.

  • ...


To apply Inline Code Wizard open its action list and select appropriate
action.

To open an action list do one of the following:

  • mouse over Indicator, it will change to Indicator Minibox. Click the

Minibox arrow.
- OR -

  • press Alt-Enter


===

Hmm... Sounds kinda heavy. But again, I am not a technical writer. Now, in
the section about Intention Action:

===
Intention Action inline code wizard helps to maintain:

  • the uniform code style;

  • adherence to Java language, J2EE, corporate and personal coding

standards;

  • code consistency throughout the project


Intention Action Indicator is displayed when when caret is positioned on the
suspicious token.

To turn the particular Intention Action rule on and off do one of the
following:

  • click on the lightbulb on the left of the rule. The lighbulb becomes

gray ("turned off") or yellow ("turned on")
- OR -

  • press spacebar


To turn off all Intention Actions press ...

To configure the list of possible Intention Actions press ...

To protect the Intention Action list from modification press ...
===

And so on.

Michael J.


0
Comment actions Permalink

Excellent. Now we're talking.

David

"Jonas Kvarnstr?m" <jonkv@ida.liu.se> wrote in message
news:3E0093E2.5000402@ida.liu.se...

David J. Stennett wrote:

>

As for misspellings -- it happens. Please, when you say "there are
misspellings," can you please tell us WHERE, so we can fix them?

>

Just as an example, I pointed out the following misspellings in
http://www.intellij.net/tracker/idea/viewSCR?publicId=8190:

>

Hierachy, procces, surronding, immplemented, implementaion, enternames,
wil, occured, runninig, nota, opeartion, exisiting, seetings, VIews,
beggining, ovewritten, specifiy, entires, Deafault, avalable, occurence,
bundeled, Maximim, reusethe, debugget, detectes, supeclass, Memebers,
refatoring, incompilable (uncompilable), qualificators (qualifiers? or
what?), Applyng, ha ve, initilization, overriden, jav.lang, upcasted
(shouldn't this be "upcast"?), methos, helpfull, heterogenous,
infrastucture, servies, approriate, refere.

>

These are over 40 misspellings that would have been caught by a spell
checker.

>


0
Comment actions Permalink

David,

I have spent about 3 hrs thinking over my message, and you have not
responded. Early Christmas transforming smoothly to New Year holidays, eh?
;)) Hope you will give your vision on this topic later.

HC & HNY, Michael.


0
Comment actions Permalink

Michael:

What are you waiting for me to comment on? I believe I mentioned that we
are continuously writing new sections of documentation, and depending on
feedback, they'll get done in that order.

You have commented on the "style," the "use of English," but you haven't put
much forward in the realms of content, which is what we're writing. Style
is up to the individual documentation writer -- we're trying to create
"conventions" so we all don't use differing words for the same object, this
much I agree. To me, things like "How to Read Help" seems self-evident, so
you may want to help us with examples (who else has such a thing, so we can
learn) -- because "How to Read Help" can slide into "How to read How to Read
Help," et cetera, ad infintum! Therefore, since we're limited in resouces
(man power, learning curves, etc...), we have to focus on certain apects
which we GET FEEDBACK ON. ;) Otherwise, we do whatever our little hearts
desire if nobody says anything.

So, my question to you is: What functions are you having problems
understanding? (or did you have understading?)

Keep the comments coming! And if I haven't answered your previous missive,
please feel free to post it again, or email me directly (or both) at:
david@intellij.com

Best!

David




"Michael Jouravlev" <mikus@mail.ru> wrote in message
news:aug1j8$to8$1@is.intellij.net...

David,

>

I have spent about 3 hrs thinking over my message, and you have not
responded. Early Christmas transforming smoothly to New Year holidays, eh?
;)) Hope you will give your vision on this topic later.

>

HC & HNY, Michael.

>
>


0

Please sign in to leave a comment.