Poll: What do you want in GWT documentation?
Bruce Johnson
We're brainstorming about some new documentation approaches as part of an effort to improve the GWT documentation. Your feedback is vitally important to so that we can make the GWT documentation significantly more useful than it is at present. Please answer at least the "High-priority" section and then, if you would be so kind, comment on the use cases below.
The time you take to reply will be a good investment! We'd love to get at least a few dozen replies, if not hundreds!
Thanks,
Bruce
=== High-priority questions in case you don't want to read anything else ===
- What is your screen resolution? (Hypothesis: developers have a much higher average resolution than end users)
- Is your monitor oriented as landscape or portrait? (that is, is it wider than it is tall or vice-versa?)
- How important is each of the following to you? Please rank them in priority order
+ search
+ "related topics" links
+ table of contents
+ index
+ per-topic user-supplied comments
+ speed
+ reading the documentation in a language other than English
- Is javadoc totally sufficient to you for the following...
+ API reference doc
+ Narrative doc, like the stuff that's in the GWT Developer Guide
- If you had to pick one, which would you rather have?
+ good answers quickly on the GWT Developer Forum or
+ extensive, easy-to-use documentation?
- What are your 3 favorite examples of technical doc? (doesn't have to be a web site per se)
=== Use cases, please comment if you disagree or see anything that's missing ===
1) You are brand new to GWT
1.1) You want to get a sample up and running quickly
(everybody likes to see something run)
1.2) You want to get an overview of the breadth of the topics and rough organizations of the concepts and see how they relate to each other
For example, you might ask, "What all can GWT do?"
1.3 ) You start trying to write some new code in GWT, but you haven't memorized anything yet
For example, you might ask, "What's the name of that interface I have to implement? Module? No wait, it's called EntryPoint...I think"
2) You are using GWT for a real project
2.1) You have heard a GWT-specific term, but you don't really know what it is and want to learn more
For example, "What is deferred binding?"
2.2) You want to know how GWT deals with a particular subject (e.g. I18N) but aren't sure about GWT-specific terminology
For example, "How can I format this currency value to display to a German user?"
2.3) You have an actual problem and need an answer
For example, "Why am I getting this error message?"
2.4) You just want to learn more about GWT by stumbling upon interesting topics
For example, "I wonder if there's a more efficient way to deal with multiple static images?"
2.5) You want the GWT documentation to be "always up"
For example, you flip back and forth to it while writing code.
3) You are becoming a GWT guru
3.1) You want to answer other people's questions by pasting URLs to documentation topics
For example, "The answer to your question is discussed in the GWT Widget Developers' guide <here>..."
3.2) You need to read a lot of detailed exposition about complex topics that you'd rather not have to look at normally
For example, "What are the ordering guarantees of deferred binding generators?"
Jeff Larsen
higher
average resolution than end users)
1280x1024
- Is javadoc totally sufficient to you for the following...
+ API reference doc
+ Narrative doc, like the stuff that's in the GWT Developer Guide
No, ideally, there would be examples for everything. I know there is
the kitchen sink example, but for me, 10 lines of code is generally
worth 5 paragraphs worth of explanation.
- How important is each of the following to you? Please rank them in
priority order
+ per-topic user-supplied comments
+ table of contents
+ index
+ search
+ "related topics" links
+ speed
+ reading the documentation in a language other than English
- What are your 3 favorite examples of technical doc? (doesn't have to
be a
web site per se)
I don't have one specifically, but examples, examples examples.
Reading code is much more succinct way of demonstrating information to
me vs some lengthy explanation of why something works that way. If I
don't understand how to get something to work, then your explanations
on the minutia on why things work a specific way become either a giant
mess of me trying to figure out what you're talking about or me just
saying screw it, and moving on.
> 1.3) You start trying to write some new code in GWT, but you haven't
Sandy McArthur
the Javadocs that are available via the IDE's quickdoc lookup feature.
Finally, when starting from scratch I like tutorial guides that walk
you through a feature so you can get something up and running quickly.
On 9/13/07, Bruce Johnson <br...@google.com> wrote:
> Hi everyone,
>
> We're brainstorming about some new documentation approaches as part of an
> effort to improve the GWT documentation. Your feedback is vitally important
> to so that we can make the GWT documentation significantly more useful than
> it is at present. Please answer at least the "High-priority" section and
> then, if you would be so kind, comment on the use cases below.
>
> The time you take to reply will be a good investment! We'd love to get at
> least a few dozen replies, if not hundreds!
>
> Thanks,
> Bruce
>
> === High-priority questions in case you don't want to read anything else ===
> - What is your screen resolution? (Hypothesis: developers have a much higher
> average resolution than end users)
High screen resolution 1680x1050 but I don't like my browser wider
than about 1000 pixel. Reading wide columns of text is hard on the
user's brain and has poor usability.
> - Is your monitor oriented as landscape or portrait? (that is, is it wider
> than it is tall or vice-versa?)
landscape
> - How important is each of the following to you? Please rank them in
> priority order
1. "related topics" links (lots of @see tags please)
2. speed (quickdocs are the fastest to load)
3. search
4. index
> + table of contents
> + per-topic user-supplied comments
> + reading the documentation in a language other than English
>
> - Is javadoc totally sufficient to you for the following...
> + API reference doc
> + Narrative doc, like the stuff that's in the GWT Developer Guide
Javadoc meets most of my needs. If you're going to embed narrative
docs in the Javadoc put it on the package page.
> - If you had to pick one, which would you rather have?
> + good answers quickly on the GWT Developer Forum or
* extensive, easy-to-use documentation!
> === Use cases, please comment if you disagree or see anything that's missing
> ===
> 1) You are brand new to GWT
> 1.1) You want to get a sample up and running quickly
> (everybody likes to see something run)
Very, very true.
> 1.2) You want to get an overview of the breadth of the topics and rough
> organizations of the concepts and see how they relate to each other
> For example, you might ask, "What all can GWT do?"
By the time I'm hitting the docs of a new product I tend to have an
idea already what the product does from marketing or external buzz.
> 1.3 ) You start trying to write some new code in GWT, but you haven't
> memorized anything yet
> For example, you might ask, "What's the name of that interface I have to
> implement? Module? No wait, it's called EntryPoint...I think"
I would start looking for example projects that demo a feature and
would then either skim their docs or sources.
> 2) You are using GWT for a real project
> 2.1) You have heard a GWT-specific term, but you don't really know what it
> is and want to learn more
> For example, "What is deferred binding?"
I'd search a TOC or index.
> 2.2) You want to know how GWT deals with a particular subject (e.g. I18N)
> but aren't sure about GWT-specific terminology
> For example, "How can I format this currency value to display to a German
> user?"
I'd start with the Javadocs.
> 2.3) You have an actual problem and need an answer
> For example, "Why am I getting this error message?"
If the stack trace doesn't help me find relevant Javadocs then I google it.
> 2.4) You just want to learn more about GWT by stumbling upon interesting
> topics
> For example, "I wonder if there's a more efficient way to deal with multiple
> static images?"
I don't think people ponder about all the things they don't know. They
have to trip over something that can help them. Cross referencing
things (@see) can help me stumble on new features and what's new
articles and change logs can help too.
> 2.5) You want the GWT documentation to be "always up"
> For example, you flip back and forth to it while writing code.
True. Quickdocs are weak when it comes to exploring an API.
> 3) You are becoming a GWT guru
> 3.1) You want to answer other people's questions by pasting URLs to
> documentation topics
> For example, "The answer to your question is discussed in the GWT Widget
> Developers' guide <here>..."
Sounds like a FAQ page.
> 3.2) You need to read a lot of detailed exposition about complex topics that
> you'd rather not have to look at normally
> For example, "What are the ordering guarantees of deferred binding
> generators?"
I'd expect to find this in the second paragraph (or further down) on
the Javadoc that appears in my quickdoc popup window. The first
sentence and paragraph should handle 75% of my documentation needs.
--
Sandy McArthur
"He who dares not offend cannot be honest."
- Thomas Paine
Thad Humphries
- What is your screen resolution? (Hypothesis: developers have a much higher
average resolution than end users)
1280 x 1024
- Is your monitor oriented as landscape or portrait? (that is, is it wider
than it is tall or vice-versa?) landscape
- How important is each of the following to you? Please rank them in
priority order (1 highest to 7 lowest)
4 search
3 "related topics" links
1 table of contents
2 index6+ per-topic user-supplied comments
5 speed
7 reading the documentation in a language other than English
- Is javadoc totally sufficient to you for the following...
+ API reference doc
Yes, but some elaboration would be good.
+ Narrative doc, like the stuff that's in the GWT Developer Guide
Put more of this in the JavaDoc
- If you had to pick one, which would you rather have?
+ good answers quickly on the GWT Developer Forum or
+ extensive, easy-to-use documentation?
The docs, hands down. And in a means I can copy and use locally without going
to the net.
- What are your 3 favorite examples of technical doc? (doesn't have to be a
web site per se)
Sun's Javadoc--lots of detail
Apache XML's Xalan and Xerces. Details, examples, how to's.
Manuals for the old InterBase 6 --
(http://www.firebirdsql.org/index.php?op=doc#category_9) In particular, the
Embedded SQL Guide was very useful.
Peter Blazejewicz
> - What is your screen resolution? (Hypothesis: developers have a much higher
> average resolution than end users)
1280x1024
> - Is your monitor oriented as landscape or portrait? (that is, is it wider
> than it is tall or vice-versa?)
landscape
> - How important is each of the following to you? Please rank them in
> priority order
+ search
+ "related topics" links
+ per-topic user-supplied comments
+ speed
+ table of contents
+ index
+ reading the documentation in a language other than English
> - Is javadoc totally sufficient to you for the following...
> + API reference doc
> + Narrative doc, like the stuff that's in the GWT Developer Guide
I would like to see cheat sheets, similiar to that one:
http://huseyint.com/projeler/extjs-cheat-sheets/Ext_Cheat_Sheet-1-1280x1024.png
in narrative docs
> - If you had to pick one, which would you rather have?
+ extensive, easy-to-use documentation?
> 1) You are brand new to GWT
> 1.1) You want to get a sample up and running quickly
> (everybody likes to see something run)
True, but samples should be easy to follow. What is not so easy for me
in current examples is that you are using many inline classes/
interfaces event nested ones which make class/object design in apps
like kitchen sink hard to follow. Current examples shows that working
app could be written with minimal coding and thanks to java oop
features even within single .java file, but that is not necesseirly
good way of showing samples
> 1.3) You start trying to write some new code in GWT, but you haven't
> memorized anything yet
I want cheat sheets
> 2.4) You just want to learn more about GWT by stumbling upon interesting
> topics
> For example, "I wonder if there's a more efficient way to deal with multiple
> static images?"
I would like to read technical docs, e.g. sessions documents form past
conferences presos given by GWT team. Usually such docs covers non
common topics in depth.
regards,
Peter
GregD
GWT can do something unless you have actual working code where GWT is
DOING it.
If you have that code, you should make it easily available, so that a
programmer who wants to do that thing, to, can find it, and use it.
For example, have a hyperlink from the documentation to the page where
the code sample is posted.
This is an open-source project. If you can't test the feature with
code that can be publicly shown, then you probably can't reasonably
claim that GWT supports the feature.
The other thing that's really missing from a docs perspective is "AJAX
for Java Programmers". I am a Java programmer. I am used to UI
widgets that come reasonably designed out of the box. Having to
provide CSS in order to make the widgets functional was a big
surprise.
I was "sold" GWT as "the Java Programmer's way to make JavaScript web
pages, without having to dirty yourself with JavaScript." Easy to
find documentation from that perspective would be helpful. Especially
a "essential parts of Java that you can't use with GWT" list
(System.arrayCopy, sorted sets immediately come to mind).
I do my programming in Eclipse. So JavaDoc is a good way to get
information to me about a specific routine. The place where the GWT
documentation falls down is the "how do I?" and "why does this
happen?"
Greg
Ping
- What is your screen resolution? (Hypothesis: developers have a much
higher
average resolution than end users)
1280x1024
- Is your monitor oriented as landscape or portrait? (that is, is it
wider
than it is tall or vice-versa?)
landscape
- How important is each of the following to you? Please rank them in
priority order
4 search
3 "related topics" links
7 table of contents
5 index
6 per-topic user-supplied comments
2 speed
1 reading the documentation in a language other than English
- Is javadoc totally sufficient to you for the following...
+ API reference doc
Yes
+ Narrative doc, like the stuff that's in the GWT Developer Guide
No
- If you had to pick one, which would you rather have?
+ good answers quickly on the GWT Developer Forum or
+ extensive, easy-to-use documentation?
A good documentation eliminates most of the questions anyway. The
developer forum questions should evolve to more complex questions that
brings value over the documentation.
- What are your 3 favorite examples of technical doc? (doesn't have to
be a
web site per se)
1. Hibernate (core) documentation is great. The index is well divided,
the information goes from simple to thorough, I can get what I need to
know very quickly
2. Sun Javadocs covers pretty much all of the usual and non-usual stuff
Nathan Williams
> - What is your screen resolution? (Hypothesis: developers have a much higher
> average resolution than end users)
3200x1200 @work (across two displays)
1920x1080 @home
> - Is your monitor oriented as landscape or portrait? (that is, is it wider
> than it is tall or vice-versa?)
landscape
> - How important is each of the following to you? Please rank them in
> priority order
+ speed (most important)
+ table of contents
+ index
+ search
+ "related topics" links
+ per-topic user-supplied comments
+ reading the documentation in a language other than English (least
important)
> - Is javadoc totally sufficient to you for the following...
> + API reference doc
> + Narrative doc, like the stuff that's in the GWT Developer Guide
For quick reference, Javadoc is great, but topical content doesn't
always map well to a particular class or package. The guide works
better for that.
It would be nice to have the JDK emulation specs in Javadoc somewhere.
> - If you had to pick one, which would you rather have?
> + good answers quickly on the GWT Developer Forum or
> + extensive, easy-to-use documentation?
Documentation will always have limits, so I'd have to choose the
forum. Ideally there would be a circular relationship, where FAQs on
the forum fed back into the documentation process. The current KB
topics have some good info, but seem isolated.
As the documentation becomes more dynamic, it would be nice if there
were an easy way to keep up with new additions.
nathan
1.) 1920x1200
2.) 1680x1050
3.) 1280x1024
How important is each of the following to you? Please rank them in
priority order...
1.) per-topic user-supplied comments
2.) search
3.) table of contents
4.) "related topics" links
5.) index
6.) speed
7.) reading the documentation in a language other than English
Is javadoc totally sufficient to you for the following...
1.) API reference doc
Answer: Yes
2.) Narrative doc, like the stuff that's in the GWT Developer
Guide
Answer: Yes, as long as its online and indexed by Google
for easy searching.
If you had to pick one, which would you rather have? Extensive, easy-
to-use documentation?
What are your 3 favorite examples of technical doc? (doesn't have to
be a web site per se)
1.) PHP.net, not the cleanest and most up to date documetion, but
I really like the user comments attached to each topic / funciton.
2.) MySQL & PostgreSql, with their site being indexed by Google,
it makes it really easy to locate an answer and then link back to the
table of contents to view related information
3.) All little different, but I just recently had to do a lot of
ZPL output for Zebra's label printers. Found their PDF documentation
to be amazing.
1) You are brand new to GWT
1.1) You want to get a sample up and running quickly
(everybody likes to see something run)
Agree, but a lot of samples are usually way to simplistic
in that they really don't grab my attention.
1.2) You want to get an overview of the breadth of the topics and
rough organizations of the concepts and see how they relate to each
other
For example, you might ask, "What all can GWT do?"
>
> 1.3) You start trying to write some new code in GWT, but you haven't
Andrej
> === High-priority questions in case you don't want to read anything else ===
> - What is your screen resolution? (Hypothesis: developers have a much higher
> average resolution than end users)
1) 1920x1200
2) 1680x1050
>
> - Is your monitor oriented as landscape or portrait? (that is, is it wider
> than it is tall or vice-versa?)
landscape
>
> - How important is each of the following to you? Please rank them in
> priority order
100% - search
20% - "related topics" links
10% - table of contents
10% - index
30% - per-topic user-supplied comments
80% - speed
0% - reading the documentation in a language other than English
> - Is javadoc totally sufficient to you for the following...
> + API reference doc
> + Narrative doc, like the stuff that's in the GWT Developer Guide
100% - Javadocs available via the IDE
> - What are your 3 favorite examples of technical doc? (doesn't have to be a
> web site per se)
php.net dcumentation
Maciej Matecki
> Hi everyone,
Hello,
>
[cut]
> === High-priority questions in case you don't want to read anything else ===
> - What is your screen resolution? (Hypothesis: developers have a much higher
> average resolution than end users)
1400x1050
> - Is your monitor oriented as landscape or portrait? (that is, is it wider
> than it is tall or vice-versa?)
>
it's wider than it's tall :)
> - How important is each of the following to you? Please rank them in
> priority order
+ per-topic user-supplied comments
+ "related topics" links
+ search
+ table of contents
+ index
+ speed
+ reading the documentation in a language other than English
>
> - Is javadoc totally sufficient to you for the following...
+ API reference doc
+ Narrative doc, like the stuff that's in the GWT Developer Guide
> - If you had to pick one, which would you rather have?
+ good answers quickly on the GWT Developer Forum or
> - What are your 3 favorite examples of technical doc? (doesn't have to be a
> web site per se)
Sun's Javadoc
Hibernate docs http://www.hibernate.org/hib_docs/v3/reference/en/html/
Regards,
Maciej Matecki
Toon...@googlemail.com
to examples.
Take as an example
http://code.google.com/webtoolkit/documentation/com.google.gwt.user.client.ui.Tree.html
It has a image of one example and code for a different one. And maybe
the example should have at least one node that itself is a tree (since
that is an essential characteristic of tree).
And why use images rather than live GWT gadgets? Why isn't GWT used in
the documentation pages? I'd like to click on the tree on the
documentation page and be able to see how it works.
Best,
-ken
gregor
On Sep 13, 4:31 pm, "Bruce Johnson" <br...@google.com> wrote:
> Hi everyone,
>
> We're brainstorming about some new documentation approaches as part of an
> effort to improve the GWT documentation. Your feedback is vitally important
> to so that we can make the GWT documentation significantly more useful than
> it is at present. Please answer at least the "High-priority" section and
> then, if you would be so kind, comment on the use cases below.
>
> The time you take to reply will be a good investment! We'd love to get at
> least a few dozen replies, if not hundreds!
>
> Thanks,
> Bruce
>
> === High-priority questions in case you don't want to read anything else ===
> - What is your screen resolution? (Hypothesis: developers have a much higher
> average resolution than end users)
>
1280 x 1024
> - Is your monitor oriented as landscape or portrait? (that is, is it wider
> than it is tall or vice-versa?)
landscape
>
> - How important is each of the following to you? Please rank them in
> priority order
> + 5 search
> + 3= "related topics" links
> + 1= table of contents
> + 1= index
> + 3= per-topic user-supplied comments
> + 6 speed
> + 7 reading the documentation in a language other than English
>
> - Is javadoc totally sufficient to you for the following...
> + API reference doc
> + Narrative doc, like the stuff that's in the GWT Developer Guide
i have found the developer guide very useful in getting started, more
so than the Javadoc, mainly becasue of the explanations and examples
in easy to read format. I would expand on these narratives in the user
guide. Javadoc more useful now. I find that the lack of inherited
methods in the class developer guides is annoying as it doesn't give
the complete picture (a problem until you get more familiar with the
class hierarchies). I would consider either incuding inherited methods
with links to their class of origin in the developer guide, or
removing them altogether with a simple link to the actual Javadoc. Or
maybe have them both up together in a tabbed panel so develper guide
tab concentrates on the how's and why's narrative and javadoc tab the
formal specification of the class.
>
> - If you had to pick one, which would you rather have?
> + good answers quickly on the GWT Developer Forum or
> + extensive, easy-to-use documentation?
I want good base documentation first (more organised and faster than
forum). Forum better for discussions on tricky issues, known
workarounds and ways forward.
>
> - What are your 3 favorite examples of technical doc? (doesn't have to be a
> web site per se)
Sun's javadoc
Hibernate
W3C CSS guides seem pretty good (but I'm a newbie at CSS)
>
> === Use cases, please comment if you disagree or see anything that's missing
> ===
> 1) You are brand new to GWT
> 1.1) You want to get a sample up and running quickly
> (everybody likes to see something run)
>
> 1.2) You want to get an overview of the breadth of the topics and rough
> organizations of the concepts and see how they relate to each other
> For example, you might ask, "What all can GWT do?"
>
> 1.3) You start trying to write some new code in GWT, but you haven't
Danny
On Sep 13, 11:31 am, "Bruce Johnson" <br...@google.com> wrote:
> Hi everyone,
>
> We're brainstorming about some new documentation approaches as part of an
> effort to improve the GWT documentation. Your feedback is vitally important
> to so that we can make the GWT documentation significantly more useful than
> it is at present. Please answer at least the "High-priority" section and
> then, if you would be so kind, comment on the use cases below.
>
> The time you take to reply will be a good investment! We'd love to get at
> least a few dozen replies, if not hundreds!
>
> Thanks,
> Bruce
>
> === High-priority questions in case you don't want to read anything else ===
> - What is your screen resolution? (Hypothesis: developers have a much higher
> average resolution than end users)
>
1280x800 (laptop) + 1024x768 (desktop)
> - Is your monitor oriented as landscape or portrait? (that is, is it wider
> than it is tall or vice-versa?)
>
Landscape
> - How important is each of the following to you? Please rank them in
> priority order
> 1 + search
> 5 + "related topics" links
> 4 + table of contents
> 3 + index
> 6 + per-topic user-supplied comments
> 2 + speed
> 7 + reading the documentation in a language other than English
>
> - Is javadoc totally sufficient to you for the following...
> + API reference doc
No
>
> - If you had to pick one, which would you rather have?
> + good answers quickly on the GWT Developer Forum or
> + extensive, easy-to-use documentation?
I had rather have extensive, easy-to-use documentation with sample
code.
>
> - What are your 3 favorite examples of technical doc? (doesn't have to be a
> web site per se)
1. O'Reilly Technical Books (e.g., Java in a Nutshell)
2. MySQL 5.0 User Guide (web-based with links and search)
3. Google search (not a guide, but where I go to first to find answers
to a problem))
>
> === Use cases, please comment if you disagree or see anything that's missing
> ===
> 1) You are brand new to GWT
> 1.1) You want to get a sample up and running quickly
> (everybody likes to see something run)
>
> 1.2) You want to get an overview of the breadth of the topics and rough
> organizations of the concepts and see how they relate to each other
> For example, you might ask, "What all can GWT do?"
>
> 1.3) You start trying to write some new code in GWT, but you haven't
> memorized anything yet
> For example, you might ask, "What's the name of that interface I have to
> implement? Module? No wait, it's called EntryPoint...I think"
Everyone is still relatively new to GWT, but I was new to GWT and
Java. One of the first and best things I ever did was to install
Eclipse. The next was buying an O'Reilly book on Java. I hate typing
code. My first inclination is to cut and paste some sample code, that
works, and make it do things like the application I have in mind. I
am always copying code, mine and others, and refining it. If I see
similar processes, etc., I build procedures/methods. I do not
memorize/remember anything: I keep a dairy of what I am doing, so that
I can go back to see what I did and how. When I get EntryPoint code
working, for example, I will cut and paste it into wherever it is
needed next. You might say that I develop by hacking. GWT/Java/
Eclipse provide me the tools to do the coding I do best.
>
> 2) You are using GWT for a real project
> 2.1) You have heard a GWT-specific term, but you don't really know what it
> is and want to learn more
> For example, "What is deferred binding?"
>
> 2.2) You want to know how GWT deals with a particular subject (e.g. I18N)
> but aren't sure about GWT-specific terminology
> For example, "How can I format this currency value to display to a German
> user?"
>
> 2.3) You have an actual problem and need an answer
> For example, "Why am I getting this error message?"
>
> 2.4) You just want to learn more about GWT by stumbling upon interesting
> topics
> For example, "I wonder if there's a more efficient way to deal with multiple
> static images?"
>
> 2.5) You want the GWT documentation to be "always up"
> For example, you flip back and forth to it while writing code.
>
Yes, GWT documentation always up is great, but it has to be searchable
with referencing links. Good documentation, with good working
samples, and a forum/group where answers to questions are found and
real-life examples of how others are doing it. These are
indispensable.
> 3) You are becoming a GWT guru
> 3.1) You want to answer other people's questions by pasting URLs to
> documentation topics
> For example, "The answer to your question is discussed in the GWT Widget
> Developers' guide <here>..."
>
> 3.2) You need to read a lot of detailed exposition about complex topics that
> you'd rather not have to look at normally
> For example, "What are the ordering guarantees of deferred binding
> generators?"
I may never become a GWT guru, but it would be nice to pay back some
of the help I have received. I never cease to be amazed by people who
are willing to share information about what they are doing. Open
source and open information are certainly moving information
technology forward at a pace now more rapid than anything in the past.
Dzmitry Lazerka
landscape both
0. EXAMPLES of every feature, samples contain only basics.
1. "related topics" links
2. search
3. others don't matter
> + Narrative doc, like the stuff that's in the GWT Developer Guide
> + extensive, easy-to-use documentation?
> - What are your 3 favorite examples of technical doc?
1. PostgreSQL (though not PDF)
2. Apache HTTPD
3. Tomcat
> 1.2) You want to get an overview of the breadth of the topics and rough
> organizations of the concepts and see how they relate to each other
> For example, you might ask, "What all can GWT do?"
Nobody understands that it is very informative to say "What CANNOT GWT
do?" along with. Brag.
Thank you!
Ksenia
> - What is your screen resolution? (Hypothesis: developers have a much higher
> average resolution than end users)
1280x1024
> - Is your monitor oriented as landscape or portrait? (that is, is it wider
> than it is tall or vice-versa?)
landscape
> - How important is each of the following to you? Please rank them in
> priority order
1) index
2) search
3) speed
4) "related topics" links
5) table of contents
6) per-topic user-supplied comments
7) reading the documentation in a language other than English
> - Is javadoc totally sufficient to you for the following...
Narrative doc, like the stuff that's in the GWT Developer Guide
> - If you had to pick one, which would you rather have?
extensive, easy-to-use documentation?
> === Use cases, please comment if you disagree or see anything that's missing
> ===
> 1) You are brand new to GWT
> 1.1) You want to get a sample up and running quickly
> (everybody likes to see something run)
true
> 1.2) You want to get an overview of the breadth of the topics and rough
> organizations of the concepts and see how they relate to each other
> For example, you might ask, "What all can GWT do?"
this type of documents rarely gives good understanding of the
technology
> 1.3) You start trying to write some new code in GWT, but you haven't
> memorized anything yet
> For example, you might ask, "What's the name of that interface I have to
> implement? Module? No wait, it's called EntryPoint...I think"
That information is usually easy to find, so that's never a problem
> 2) You are using GWT for a real project
> 2.1) You have heard a GWT-specific term, but you don't really know what it
> is and want to learn more
> For example, "What is deferred binding?"
That's why an extensive help with a table of contents would really
help
> 2.2) You want to know how GWT deals with a particular subject (e.g. I18N)
> but aren't sure about GWT-specific terminology
> For example, "How can I format this currency value to display to a German
> user?"
Again, you go to the I18N and look in the table of contents
> 2.3) You have an actual problem and need an answer
> For example, "Why am I getting this error message?"
I'd go to the Developers' Forum
> 2.4) You just want to learn more about GWT by stumbling upon interesting
> topics
> For example, "I wonder if there's a more efficient way to deal with multiple
> static images?"
Doesn't happen too often
> 2.5) You want the GWT documentation to be "always up"
> For example, you flip back and forth to it while writing code.
No
dupre002
> - What is your screen resolution? (Hypothesis: developers have a much higher
> average resolution than end users)
1280x1024
>
> - Is your monitor oriented as landscape or portrait? (that is, is it wider
> than it is tall or vice-versa?)
landscape
> - How important is each of the following to you? Please rank them in
> priority order
search
table of contents
"related topics" links
per-topic user-supplied comments
index
speed
reading the documentation in a language other than English
> - Is javadoc totally sufficient to you for the following...
> + API reference doc
> + Narrative doc, like the stuff that's in the GWT Developer Guide
I like javadoc for the api reference, but not necessarily for the
developer guide information.
> - If you had to pick one, which would you rather have?
> + good answers quickly on the GWT Developer Forum or
> + extensive, easy-to-use documentation?
Probably documentation. I can spend a lot of time looking through
posts that don't apply to my problem.
> - What are your 3 favorite examples of technical doc? (doesn't have to be a
> web site per se)
I like the apache websites like Tomcat and Struts.
I also agree with calling out the "essential parts of Java that you
can't use with GWT" list in a better way would help (I ended up
bookmarking the page because I can't remember where it was stored).
John Gunther
else ===
- What is your screen resolution? (Hypothesis: developers have a much
higher
average resolution than end users)
1024x768
- Is your monitor oriented as landscape or portrait? (that is, is it
wider
than it is tall or vice-versa?)
landscape
- How important is each of the following to you? Please rank them in
priority order
+ search
+ index
+ "related topics" links
+ table of contents
+ per-topic user-supplied comments
+ speed (as long as it takes less than 5 seconds per query--otherwise
it gets a higher priority)
+ reading the documentation in a language other than English
- Is javadoc totally sufficient to you for the following...
+ API reference doc
Big area that could be improved: one simple fully understandable for
dummies example of every method right in the API.
Examples should be short, it is an API after all, but I think they
need to be in there.
+ Narrative doc, like the stuff that's in the GWT Developer Guide
I think these docs really helped me get started. Their shortness was,
for me, one of their best features, since I didn't need to wade
through a lot of stuff I didn't need to know. More detailed technical
information is needed, but try to keep these docs short.
- If you had to pick one, which would you rather have?
+ good answers quickly on the GWT Developer Forum or
+ extensive, easy-to-use documentation?
Ideally, if there is only one right answer, it should be in the docs.
When there are many different approaches
and no clear right answer, the forum is best. The truth should be in
the API docs, the opinions in the forum.
- What are your 3 favorite examples of technical doc? (doesn't have to
be a
web site per se)
Elisabeth Castro's "HTML for the World Wide Web" (Peachpit Press),
Harbison and Steele's "C, a Reference Manual"
(Prentice-Hall) and the Javadocs for the Concurrency API of the JDK,
available here:
https://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/package-summary.html#package_description
Latter is an example of how useful carefully constructed examples can
be right inside the API docs.
=== Use cases, please comment if you disagree or see anything that's
missing
===
1) You are brand new to GWT
1.1) You want to get a sample up and running quickly
(everybody likes to see something run)
1.2) You want to get an overview of the breadth of the topics and
rough
organizations of the concepts and see how they relate to each other
For example, you might ask, "What all can GWT do?"
1.3) You start trying to write some new code in GWT, but you haven't
In the beginning, I experienced the 1.x use cases fairly equally, but
now that I'm on a real project,
it's almost exclusively 2.2 & 2.3. As far as I'm concerned, these are
the "must have" use cases.
Some specific comments/ideas on the docs:
Overall, your docs are quite good, better than most of the Java JDK
docs I've read, for example. Without them, I'd be lost. Thanks. What
you've done is great, I just wish there was more of it!
I've been referring frequently to Elisabeth Castro's introductory HTML/
CSS book, and to other on-line HTML/CSS resources, in order understand
how to use GWT properly. Many API refs implicitly assume you know this
stuff. Example: how can you create an empty Image unless you know the
1x1 transparent pixel trick? Docs could help here with an appropriate
one-liner like "To create a completely empty image, use a 1x1
transparent pixel image, as described here." What could help a lot
here is one line for each widget, such as "The Image object is
implemented with an HTML img tag" and then a link to the appropriate
docs for that HTML or CSS feature. One click to drill down to the
relevant HTML/CSS would be "WOW" doc feature for me. Another example:
without a basic knowledge of Javascript/CSS naming conventions how are
you supposed to guess that the DOM.setStyleAttribute function requires
camelCasing of the attribute names? These are "documentation black
holes" the uninitiated can fall into, costing many hours of effort. A
few tips in the docs and/or links to related HTML/CSS material would
go a long way towards plugging up such holes and making my trips to
the HTML/CSS web sites less frequent and more orderly/productive.
A pet peeve of mine (not exactly a doc issue): not enough convenience
functions. A convenience function is worth a 1,000 words of
documentation. Why do I have to go to the DOM just to set the
background color, for example? My suggestion: take a hard look at the
Swing API, see if it provides a feature that can be easily implemented
with a convenience function, and if so, assume it is important enough
to just add it in (you might prefer to look at several GUI toolkits
and develop a consensus to determine which convenience functions
"everyone" assumes should in be there, but that's the basic idea). For
new user's coming from conventional desktop GUI toolkits with minimal
HTML/CSS experience, they'll feel a lot better if more of the things
they expect to be there are where they expect them to be.
And such functions will also save experienced users typing, since
their IDE's will be able to in effect "do CSS names" to the extent
that these methods are right in, say, the Widget class.
On Sep 13, 11:31 am, "Bruce Johnson" <br...@google.com> wrote:
> 1.3) You start trying to write some new code in GWT, but you haven't
night...@gmail.com
> - What is your screen resolution? (Hypothesis: developers have a much higher
> average resolution than end users)
1440x900 + 1280x1024
> - Is your monitor oriented as landscape or portrait? (that is, is it wider
> than it is tall or vice-versa?)
Both landscape.
> - How important is each of the following to you? Please rank them in
> priority order
1. index
2. table of contents
Right now, GWT is still small enough to have a meaningful TOC and
index.
3. "related topics" links
4. per-topic user-supplied comments
5. speed
Not an issue if a tarball can be used locally.
6. search
Always available through regular Google + site:
7. reading the documentation in a language other than English
> - Is javadoc totally sufficient to you for the following...
> + API reference doc
> + Narrative doc, like the stuff that's in the GWT Developer Guide
Javadoc + package pages are sufficient for a reference. A Developer
Guide should not be extracted from the Javadoc, because the
granularity has to be different.
> - If you had to pick one, which would you rather have?
> + good answers quickly on the GWT Developer Forum or
> + extensive, easy-to-use documentation?
"extensive, easy-to-use documentation", because there is absolutely no
warranty to have a quick whatever the timezone.
> - What are your 3 favorite examples of technical doc? (doesn't have to be a
> web site per se)
1. The Java combination : Tutorial + Dedicated documentation per API +
Javadoc
2. PHP : one manual + contributed examples, but less usable for the
beginners compared to Java, because they have too know beforehand the
names of the modules that have been integrated.
3. Some parts of the old MSDN Library, which was very rich in cross-
references, but had an awkward navigation model.
> === Use cases, please comment if you disagree or see anything that's missing
> ===
> 1) You are brand new to GWT
[...]
> 1.2) You want to get an overview of the breadth of the topics and rough
> organizations of the concepts and see how they relate to each other
> For example, you might ask, "What all can GWT do?"
Yes, but it does not need to be a "runnable overview", like the Java
Swing Demo, I found it was of little use.
> 1.3) You start trying to write some new code in GWT, but you haven't
> memorized anything yet
> For example, you might ask, "What's the name of that interface I have to
> implement? Module? No wait, it's called EntryPoint...I think"
This is really done by having a tutorial or existing code. I don't
think that case is widespread.
> 2) You are using GWT for a real project
> 2.1) You have heard a GWT-specific term, but you don't really know what it
> is and want to learn more
> For example, "What is deferred binding?"
Here the problem is that "deferred binding" is not specific to GWT but
has a specific meaning in GWT ("everything loaded by the client is
'deferred binding', even resources"). So the question is more "What is
called 'deferred binding' for GWT?".
> 2.2) You want to know how GWT deals with a particular subject (e.g. I18N)
> but aren't sure about GWT-specific terminology
> For example, "How can I format this currency value to display to a German
> user?"
"Where is the text formatting package / module? If there is no
specific package, where is the text formatting Tutorial?"
[...]
> 2.4) You just want to learn more about GWT by stumbling upon interesting
> topics
> For example, "I wonder if there's a more efficient way to deal with multiple
> static images?"
Is performance part of a base documentation? I'm not sure about that
one.
> 2.5) You want the GWT documentation to be "always up"
> For example, you flip back and forth to it while writing code.
Maybe. But you also want to be sure that the documentation you flip
through applies to the version you are running, which is not always
the latest one.
[2.x] Misunderstandings
"I do this, but it does not seem to have any effect: am I missing
something obvious? Let's see the basic example in the reference
documentation, or a specific documentation linked from it. Otherwise,
let's file a bug: what is the right category for the bug?"
[2.x+] Where does that behaviour come from?
"On this element, I can call setChecked, what is the associated
behaviour? What are the other elements providing this behaviour?"
[2.x++] Deprecation
"This method is deprecated: why? what to do instead?"
[2.x#] Alternatives
This is 2.4, but reworded to remove the performance aspect: "I know I
can style a button to create this custom widget, can I use another
basic widget?" Which link us back to 2.x+.
> 3) You are becoming a GWT guru
[...]
> 3.2) You need to read a lot of detailed exposition about complex topics that
> you'd rather not have to look at normally
> For example, "What are the ordering guarantees of deferred binding
> generators?"
[3.x] Read the source Luke!
"The documentation defines the ordering guarantess of deferred
binding: where is it implemented?"
Cens
"GWT RPC is no longer tied to exclusively to servlets. New modularized
RPC server code makes it easy to connect GWT RPC to your choice of
Java back-ends."
I would like to have this issue well documented, since I didn'f find
how to use something different than a servlet.
Thank you very much.
Vincenzo Caselli
in...@censnet.it
wt
What I'd really like to be added is some best practices or design
patterns of using GWT, for example, how to handle security when using
Spring as the back end framework, how to organize the GWT classes when
implement a complex UI (a UI that has a large number of component and
as well as deep hierarchy). There are some information spread out in
the posts of this group, but I think a well organized doc is highly
needed and will be really useful.
Neeraj Upreti
=== High-priority questions in case you don't want to read anything
else ===
- What is your screen resolution? (Hypothesis: developers have a much
higher
average resolution than end users)
- Is your monitor oriented as landscape or portrait? (that is, is it
wider
than it is tall or vice-versa?)
landscape
- How important is each of the following to you? Please rank them in
priority order
+ search (5)
+ "related topics" links (6)
+ table of contents (4)
+ index (2)
+ per-topic user-supplied comments (3)
+ speed (1)
+ reading the documentation in a language other than English (7)
---------------------------------------------------------------------------------------
- Is javadoc totally sufficient to you for the following...
+ API reference doc
partially
---------------------------------------------------------------------------------------
+ Narrative doc, like the stuff that's in the GWT Developer Guide
most of the topics are sufficient but some are insufficient like one
on
javadoc annotation @gwt.typeArgs ...
-----------------------------------------------------------------------------------------
- If you had to pick one, which would you rather have?
+ good answers quickly on the GWT Developer Forum or
+ extensive, easy-to-use documentation?
good answers quickly on the GWT Developer Forum
--------------------------------------------------------------------------------------
- What are your 3 favorite examples of technical doc? (doesn't have to
be a
web site per se)
1. http://java.sun.com/developer/technicalArticles/javase/worldwind/
2. http://www.oracle.com/technology/oramag/oracle/05-sep/o55opt.html
3. http://java.sun.com/developer/Books/JDBCTutorial/index.html
------------------------------------------------------------------------------------------------------
GWBasic
I have a 17" MacBook and a MacPro with a 23" monitor. Both are
landscape. (Does anyone actually work in portrait mode???)
The topics most important to me are:
Index (I looooove the MSDN Index for C#, this is installed with Visual
Studio; I really need an alphabetical list of GWT classes.)
Related Topics
User Comments
Speed
Table-Of-Contents
Also, if you can add LOTS and LOTS and LOTS of examples, it would be
helpful. I know this takes LOTS and LOTS and LOTS of developer (cough
intern cough) time, but please be aware that an example can make a lot
more sense then 5 pages of documentation!
I haven't used JavaDoc, primarily because it's new and intimidating,
and HTML gives me the warm and fuzzies.
I tend to use documentation before forums. For me, I feel that mature
products need real documentation. Forums are not a substitue for
complete documentation.
My 3 favorite examples of Technical Documentation:
The MSDN client installed with Visual Studio, specifically for use
with C#
The PHP documentation that allows user-generated comments on each page
I don't have a 3rd...
As far as use cases for GWT documentation, there will probably also
need to be some "How do I ...", that guide the programmer in a step-by-
step manner in implementing things like AJAX, Drag-N-Drop, ect.
> 1.3) You start trying to write some new code in GWT, but you haven't
Richard Bondi
=== High-priority questions in case you don't want to read anything
else ===
- What is your screen resolution? (Hypothesis: developers have a much
higher
average resolution than end users)
1440 x 900
- Is your monitor oriented as landscape or portrait? (that is, is it
wider
than it is tall or vice-versa?)
/Landscape/
(I reshuffled with most important first)
- How important is each of the following to you? Please rank them in
priority order
+ search
+ per-topic user-supplied comments
+ table of contents
+ speed
+ "related topics" links
+ index
+ reading the documentation in a language other than English
- Is javadoc totally sufficient to you for the following...
+ /yes/ API reference doc
+ /no/ Narrative doc, like the stuff that's in the GWT Developer Guide
- If you had to pick one, which would you rather have?
/Nope: I have to have both, sorry./
+ good answers quickly on the GWT Developer Forum or
+ extensive, easy-to-use documentation?
- What are your 3 favorite examples of technical doc? (doesn't have to
be a
web site per se)
For just about everything you can do in Java, this has
a snippet of example code. If only every open source project had this
instead of torrents of (poorly written) words.
Suggestion:
- Write an exampledepot-style app that anyone can contribute GWT how-
to examples to, with a system for
verifying/voting on the examples (example votes: yes that worked for
me to, no this should not be accepted it didn't work for me, etc.)
2) http://msdn.microsoft.com (so sue me)
The sucky search sucks, and the tree aka toc is good to navigate with.
But the javadoc equivalents are excellently written, and always have
one or
more very good code examples.
3) http://www.php.net/manual/en/
The users' comments are valuable, and the table of contents is very
good.
=== Use cases, please comment if you disagree or see anything that's
missing
===
Missing:
2.6 For any given widget, you want to know how to instantiate it, and
how to code for everything it can do.
zol...@gmail.com
> - What is your screen resolution? (Hypothesis: developers have a much higher
> average resolution than end users)
1280x1024
> - Is your monitor oriented as landscape or portrait? (that is, is it wider
> than it is tall or vice-versa?)
Landscape.
> - How important is each of the following to you? Please rank them in
> priority order
+ table of contents
+ search
+ per-topic user-supplied comments
+ "related topics" links
+ index
+ speed
+ reading the documentation in a language other than English
> - If you had to pick one, which would you rather have?
+ extensive, easy-to-use documentation?
> - What are your 3 favorite examples of technical doc? (doesn't have to be a
> web site per se)
Hibernate
JBoss Seam
GWT ;-)
Regards,
Zoltan
goatstone
higher
average resolution than end users)
1024 x 768
I like to be able to view a documentation window to about 1/2 the
screen width and work on the command line or text editor in the other
half of the screen. A layout with a more liquid design is helpful
here.
- Is your monitor oriented as landscape or portrait? (that is, is it
wider
than it is tall or vice-versa?)
wider
- How important is each of the following to you? Please rank them in
priority order
+ search
3
+ "related topics" links
5
+ table of contents
1
+ index
2
+ per-topic user-supplied comments
4
+ speed
6
+ reading the documentation in a language other than English
7
- Is javadoc totally sufficient to you for the following...
+ API reference doc
+ Narrative doc, like the stuff that's in the GWT Developer Guide
I think the developer guide is really useful. I think that the
"Cookbook" style of developer guide is very useful. I find that two
developers may do the same thing in different ways but each "Recipe"
is useful. This would imply that the more "cookbook" style developer
guides, the better.
- If you had to pick one, which would you rather have?
+ good answers quickly on the GWT Developer Forum or
+ extensive, easy-to-use documentation?
This is far more useful, because many of the questions on Forums are
repeats anyway. The forum poster just hasn't found the issue in the
doc.s. Well, it is not always easy to find your particular issue in
the doc.s.
- What are your 3 favorite examples of technical doc? (doesn't have to
be a
web site per se)
O'reilly books: The Definitive Guides, Cook books and Nutshell books
MySQL, JavaScript, Java, HTML and others are great. I like books
because as reference material.
Online of coarse there are great ones.
http://php.net
http://smarty.php.net
http://dev.mysql.com/doc/
http://java.sun.com/docs/books/tutorial/
=== Use cases, please comment if you disagree or see anything that's
missing
===
1) You are brand new to GWT
Yes, but I have worked with client side code extensively and Java as
well
1.1) You want to get a sample up and running quickly
(everybody likes to see something run)
I want to understand it and work with it because this is a very new
approach for me. I would like to know what users need and build that
1.2) You want to get an overview of the breadth of the topics and
rough
organizations of the concepts and see how they relate to each other
For example, you might ask, "What all can GWT do?"
Yes
1.3) You start trying to write some new code in GWT, but you haven't
memorized anything yet
For example, you might ask, "What's the name of that interface I have
to
implement? Module? No wait, it's called EntryPoint...I think"
Well, I think, I have a handle on it even though I have not memorized
much yet.
2) You are using GWT for a real project
My real project is understanding the GWT.
2.1) You have heard a GWT-specific term, but you don't really know
what it
is and want to learn more
For example, "What is deferred binding?"
Yes
2.2) You want to know how GWT deals with a particular subject (e.g.
I18N)
but aren't sure about GWT-specific terminology
For example, "How can I format this currency value to display to a
German
user?"
Yes
2.3) You have an actual problem and need an answer
For example, "Why am I getting this error message?"
Yes
2.4) You just want to learn more about GWT by stumbling upon
interesting
topics
For example, "I wonder if there's a more efficient way to deal with
multiple
static images?"
No, I do not want to stumble on topics, even if they are interesting.
If they are interesting I would like them brought to my attention or
somehow I would be able to find them with a search engine or key words
or perhaps it is an author whose previous articles I have read and
benefited from.
2.5) You want the GWT documentation to be "always up"
For example, you flip back and forth to it while writing code.
Yes
3) You are becoming a GWT guru
I hope so.
3.1) You want to answer other people's questions by pasting URLs to
documentation topics
For example, "The answer to your question is discussed in the GWT
Widget
Developers' guide <here>..."
I want to build a search engine that helps people find the answers to
their questions.
3.2) You need to read a lot of detailed exposition about complex
topics that
you'd rather not have to look at normally
For example, "What are the ordering guarantees of deferred binding
generators?"
Well, it seems to me that this is a complete topic to begin with, and
to not get into the complexities would be to not really understand it.
Jose Collas
goatstone.com
John Gunther
source code (e.g. AbsolutePanel.java) for that widget would encourage
more people to read the top-level code, which I have found very
informative/helpful of late, but which initially I did not consult. My
own experience suggests that this great tech-doc resource is likely
under-utilized--such links could change that. If top-level code is as
information-rich in the other GWT packages as it is in UI code I've
sampled, such links could be helpful throughout the entire GWT
javadocs.
Freeland Abbott
Anil
>
> === High-priority questions in case you don't want to read anything else ===
> average resolution than end users)
the default
>
> - Is your monitor oriented as landscape or portrait? (that is, is it wider
> than it is tall or vice-versa?)
>
landscape
> - How important is each of the following to you? Please rank them in
> priority order
> + search
3
> + "related topics" links
2
> + table of contents
4
> + index
5
> + per-topic user-supplied comments
1
> + speed
6
> + reading the documentation in a language other than English
7
>
> - Is javadoc totally sufficient to you for the following...
> + API reference doc
YES. with links to online content and forums
> + Narrative doc, like the stuff that's in the GWT Developer Guide
NO
>
> - If you had to pick one, which would you rather have?
> + extensive, easy-to-use documentation?
>
> - What are your 3 favorite examples of technical doc? (doesn't have to be a
> web site per se)
Java tutorial at sun.com
>
> === Use cases, please comment if you disagree or see anything that's missing
> ===
> 1) You are brand new to GWT
> 1.1) You want to get a sample up and running quickly
> (everybody likes to see something run)
>
> 1.2) You want to get an overview of the breadth of the topics and rough
> organizations of the concepts and see how they relate to each other
> For example, you might ask, "What all can GWT do?"
>
> 1.3) You start trying to write some new code in GWT, but you haven't
> memorized anything yet
> For example, you might ask, "What's the name of that interface I have to
> implement? Module? No wait, it's called EntryPoint...I think"
>
> 2) You are using GWT for a real project
> 2.1) You have heard a GWT-specific term, but you don't really know what it
> is and want to learn more
> For example, "What is deferred binding?"
>
> 2.2) You want to know how GWT deals with a particular subject (e.g. I18N)
> but aren't sure about GWT-specific terminology
> For example, "How can I format this currency value to display to a German
> user?"
>
> 2.3) You have an actual problem and need an answer
> For example, "Why am I getting this error message?"
>
> 2.4) You just want to learn more about GWT by stumbling upon interesting
> topics
> For example, "I wonder if there's a more efficient way to deal with multiple
> static images?"
>
> 2.5) You want the GWT documentation to be "always up"
> For example, you flip back and forth to it while writing code.
>
> 3) You are becoming a GWT guru
> 3.1) You want to answer other people's questions by pasting URLs to
> documentation topics
> For example, "The answer to your question is discussed in the GWT Widget
> Developers' guide <here>..."
>
> 3.2) You need to read a lot of detailed exposition about complex topics that
> you'd rather not have to look at normally
> For example, "What are the ordering guarantees of deferred binding
> generators?"
GWT is lacking concurrent execution. Very important for me.
see
http://groups.google.com/group/Google-Web-Toolkit/msg/fcdd53868bf2824d
"need to have sound playing in parallel with web links opening up in
a browser and video playing.
As abickford said Incremental Command wont work, Can I accomplish
this
instead by running each task in a browser and spawning off these new
browsers? (minimized to avoid clutter).
Just wondering.
thanks,
Anil
"
Max
On 13 Sep., 17:31, "Bruce Johnson" <br...@google.com> wrote:
> Hi everyone,
>
> We're brainstorming about some new documentation approaches as part of an
> effort to improve the GWT documentation. Your feedback is vitally important
> to so that we can make the GWT documentation significantly more useful than
> it is at present. Please answer at least the "High-priority" section and
> then, if you would be so kind, comment on the use cases below.
sure, here we go:
> === High-priority questions in case you don't want to read anything else ===
> - What is your screen resolution? (Hypothesis: developers have a much higher
> average resolution than end users)
1400x1050
> - Is your monitor oriented as landscape or portrait? (that is, is it wider
> than it is tall or vice-versa?)
landscape
> - How important is each of the following to you? Please rank them in
> priority order
+ table of contents
+ search
+ index
+ speed
+ "related topics" links
+ per-topic user-supplied comments
+ reading the documentation in a language other than English
> - Is javadoc totally sufficient to you for the following...
+ API reference doc
+ Narrative doc, like the stuff that's in the GWT Developer Guide
> - If you had to pick one, which would you rather have?
+ extensive, easy-to-use documentation?
+ good answers quickly on the GWT Developer Forum or
> - What are your 3 favorite examples of technical doc? (doesn't have to be a
> web site per se)
http://techbase.kde.org/
http://java.sun.com/javase/reference/api.jsp
http://api.rubyonrails.org/ (could be enhanced though)
> === Use cases, please comment if you disagree or see anything that's missing
> ===
> 1) You are brand new to GWT
disagree, I have already implemented one large project with GWT,
> 1.1) You want to get a sample up and running quickly
> (everybody likes to see something run)
Full ACK, I've seen beginners capitulating because of the long
learning period for setting up GWT projects from scratch.
> 1.2) You want to get an overview of the breadth of the topics and rough
> organizations of the concepts and see how they relate to each other
> For example, you might ask, "What all can GWT do?"
agree, in some cases documentation is spread accross multiple
locations.
> 1.3) You start trying to write some new code in GWT, but you haven't
> memorized anything yet
> For example, you might ask, "What's the name of that interface I have to
> implement? Module? No wait, it's called EntryPoint...I think"
Full ACK, API docs are already very good at that, though.
> 2) You are using GWT for a real project
ACK
> 2.1) You have heard a GWT-specific term, but you don't really know what it
> is and want to learn more
> For example, "What is deferred binding?"
more or less ACK.
> 2.2) You want to know how GWT deals with a particular subject (e.g. I18N)
> but aren't sure about GWT-specific terminology
> For example, "How can I format this currency value to display to a German
> user?"
disagree.
> 2.3) You have an actual problem and need an answer
> For example, "Why am I getting this error message?"
disagree, Free Software is just superior. If you get an error, you can
look at the code as a last resort.
> 2.4) You just want to learn more about GWT by stumbling upon interesting
> topics
> For example, "I wonder if there's a more efficient way to deal with multiple
> static images?"
ACK!
> 2.5) You want the GWT documentation to be "always up"
> For example, you flip back and forth to it while writing code.
ACK
> 3) You are becoming a GWT guru
hu? I'm not the one to decide that. :-)
> 3.1) You want to answer other people's questions by pasting URLs to
> documentation topics
> For example, "The answer to your question is discussed in the GWT Widget
> Developers' guide <here>..."
Full ACK!
> 3.2) You need to read a lot of detailed exposition about complex topics that
> you'd rather not have to look at normally
> For example, "What are the ordering guarantees of deferred binding
> generators?"
disagree.
Cheers and HTH!
Max
Max
Ray Myers
> === High-priority questions in case you don't want to read anything else ===
> - What is your screen resolution? (Hypothesis: developers have a much higher
> average resolution than end users)
>
> - Is your monitor oriented as landscape or portrait? (that is, is it wider
> than it is tall or vice-versa?)
>
landscape
> - How important is each of the following to you? Please rank them in
> priority order
per-topic user-supplied comments
index
search
table of contents
speed
"related topics" links
reading the documentation in a language other than English
> - If you had to pick one, which would you rather have?
> + good answers quickly on the GWT Developer Forum or
> + extensive, easy-to-use documentation?
extensive, easy-to-use documentation?
doopa
On Sep 13, 5:31 pm, "Bruce Johnson" <br...@google.com> wrote:
> === High-priority questions in case you don't want to read anything else ===
> - What is your screen resolution? (Hypothesis: developers have a much higher
> average resolution than end users)
1920x1200
and in virtual machine
1024x768 - used for testing in other browsers/OS
> - Is your monitor oriented as landscape or portrait? (that is, is it wider
> than it is tall or vice-versa?)
Landscape
> - How important is each of the following to you? Please rank them in
> priority order
3 + search
5 + "related topics" links
2 + table of contents
1 + index
4 + per-topic user-supplied comments
6 + speed
7 + reading the documentation in a language other than English
> - If you had to pick one, which would you rather have?
> + good answers quickly on the GWT Developer Forum or
> + extensive, easy-to-use documentation?
Extensive easy to use documentation with clear example - but it
shouldn't really be an either or.
jarrod
1920x1280+1280X1024 (2 screens at work)
1280x854 (laptop)
All oriented horizontally.
1 search
2 speed
3 "related topics" links
4 index
5 table of contents
6 per-topic user-supplied comments
7 reading the documentation in a language other than English
A javadoc is important for sure. Is there a standard javadoc posted
somewhere? There are many points not covered in the existing
documentation, such as all the available elements of the module XML
(<define-property>? <replace-with>?) How about creating a DTD?
The narrative doc that's there now is nice, but it doesn't cover
enough use cases to be useful. For example, it completely lacks
documentation on deferred binding!
I would prefer extensive documentation over quick answers in the
forum.
The use cases look pretty good, but there is one MAJOR use case not
covered by GWT:
I am an HTML/JavaScript Guru, and I'm looking for ways to develop more
reliable code. I am comfortable in Java and Eclipse, but I'm no pro.
I've had a very step learning curve because I'm not as up to par on
Java as I am on JavaScript. But i still want to take advantage of GWT
for unit testing, cross-browser compatibility, etc. Your documentation
assumes everyone using GWT comes from a Java background and is
learning JS, not the other way around.
My favorite documentation? Despite the grammatical errors, FreeMarker
has a tremendous documentation library. I have yet to ask a question
it did not answer (and nearly every aspect of it has a concrete
example of code).
http://freemarker.org/docs/index.html
Finally, I'd like to recommend more documentation that integrates with
Eclipse. I'm a big fan of the Aptana project (http://www.aptana.org)
and the way they integrate with Eclipse, offering automation scripts,
etc... I know this isn't the forum for feature requests, but syntax
highlighting in native JS methods would be nice, as an example.
On Sep 13, 11:31 am, "Bruce Johnson" <br...@google.com> wrote:
> Hi everyone,
>
> We're brainstorming about some new documentation approaches as part of an
> effort to improve the GWT documentation. Your feedback is vitally important
> to so that we can make the GWT documentation significantly more useful than
> it is at present. Please answer at least the "High-priority" section and
> then, if you would be so kind, comment on the use cases below.
>
> The time you take to reply will be a good investment! We'd love to get at
> least a few dozen replies, if not hundreds!
>
> Thanks,
> Bruce
>
> === High-priority questions in case you don't want to read anything else ===
> - What is your screen resolution? (Hypothesis: developers have a much higher
> average resolution than end users)
>
> - Is your monitor oriented as landscape or portrait? (that is, is it wider
> than it is tall or vice-versa?)
>
> - How important is each of the following to you? Please rank them in
> priority order
> + search
> + "related topics" links
> + table of contents
> + index
> + per-topic user-supplied comments
> + speed
> + reading the documentation in a language other than English
>
> - Is javadoc totally sufficient to you for the following...
> + API reference doc
> + Narrative doc, like the stuff that's in the GWT Developer Guide
>
> - If you had to pick one, which would you rather have?
> + good answers quickly on the GWT Developer Forum or
> + extensive, easy-to-use documentation?
>
> - What are your 3 favorite examples of technical doc? (doesn't have to be a
> web site per se)
>
> === Use cases, please comment if you disagree or see anything that's missing
> ===
> 1) You are brand new to GWT
> 1.1) You want to get a sample up and running quickly
> (everybody likes to see something run)
>
> 1.2) You want to get an overview of the breadth of the topics and rough
> organizations of the concepts and see how they relate to each other
> For example, you might ask, "What all can GWT do?"
>
> 1.3) You start trying to write some new code in GWT, but you haven't
> memorized anything yet
> For example, you might ask, "What's the name of that interface I have to
> implement? Module? No wait, it's called EntryPoint...I think"
>
> 2) You are using GWT for a real project
> 2.1) You have heard a GWT-specific term, but you don't really know what it
> is and want to learn more
> For example, "What is deferred binding?"
>
> 2.2) You want to know how GWT deals with a particular subject (e.g. I18N)
> but aren't sure about GWT-specific terminology
> For example, "How can I format this currency value to display to a German
> user?"
>
> 2.3) You have an actual problem and need an answer
> For example, "Why am I getting this error message?"
>
> 2.4) You just want to learn more about GWT by stumbling upon interesting
> topics
> For example, "I wonder if there's a more efficient way to deal with multiple
> static images?"
>
> 2.5) You want the GWT documentation to be "always up"
> For example, you flip back and forth to it while writing code.
>
> 3) You are becoming a GWT guru
> 3.1) You want to answer other people's questions by pasting URLs to
> documentation topics
> For example, "The answer to your question is discussed in the GWT Widget
> Developers' guide <here>..."
>
jarrod
Convenience methods will come as GWT matures. But they are an
important feature of any framework.
A classic example would be Prototype JS. My biggest gripe about GWT
right now is that I'm having to write a lot of code to handle things
that could be done with one or two lines in Prototype.
If that doesn't make sense, remember that the end goal of GWT is to
allow DOM manipulation through Java. Thus, tricks like getting a
serialized string from a <form> element are easy to do in Prototype ( $
('myForm').serialize() ) where the GWT toolkit would require custom
methods and a whole bunch of mess.
I know you can do some native JS tricks, but what's the point of the
GWT framework if you do everything in JS? ;-)
toby
subdomains (e.g. for localization).
I have never seem com.google..blablabla inside of Adsense or Adwords
URLs........but the sample applications do.
Toby
Yoshiki
> - What is your screen resolution? (Hypothesis: developers have a much higher
> average resolution than end users)
1024 x 768
> - Is your monitor oriented as landscape or portrait? (that is, is it wider
> than it is tall or vice-versa?)
landscape
> - How important is each of the following to you? Please rank them in
> priority order
> + search
> + "related topics" links
> + table of contents
> + index
> + per-topic user-supplied comments
> + speed
> + reading the documentation in a language other than English
+ reading the documentation in a language other than English
+ table of contents
+ "related topics" links
+ search
> - Is javadoc totally sufficient to you for the following...
> + API reference doc
> + Narrative doc, like the stuff that's in the GWT Developer Guide
yes for API reference doc. No for Narrative doc.
> - If you had to pick one, which would you rather have?
> + good answers quickly on the GWT Developer Forum or
> + extensive, easy-to-use documentation?
+ extensive, easy-to-use documentation?
> - What are your 3 favorite examples of technical doc? (doesn't have to be a
> web site per se)
no example for now.
Regards,
Yoshiki Shibata
Travis Pouarz
We're brainstorming about some new documentation approaches as part of
an effort to improve the GWT documentation. Your feedback is vitally
important to so that we can make the GWT documentation significantly
more useful than it is at present. Please answer at least the "High-
priority" section and then, if you would be so kind, comment on the
use cases below.
The time you take to reply will be a good investment! We'd love to get
at least a few dozen replies, if not hundreds!
Thanks, Bruce
else ===
1920 x 1200 LCD (Mac OS X) for primary GWT dev.
I'll also be checking the end result on laptops that are more like my
end users might sometimes need to use: 1152 x 768 (Mac OS X), 1024 x
768 (Win XP)
> Is your monitor oriented as landscape or portrait?
Landscape
> How important is each of the following to you? Please rank them in priority order
I wouldn't change anything about the order:
+ search
+ "related topics" links
+ table of contents
+ index
+
per-topic user-supplied comments
+ speed
+ reading the documentation
in a language other than English
> Is javadoc totally sufficient to you for the following... + API reference doc
Yes.
+ Narrative doc, like the stuff that's in the GWT Developer Guide
Not completely, but it's definitely a good start, especially when
verbose about details, considerations, and approaches to problems.
And examples. Need more examples! (Examples with verbose
comments. :-) Examples can go in the API javadoc as well. (And
examples need to list their "import"s! I've seen some examples in
Google's GWT docs that were frustrating because I couldn't tell what
packages contained the classes.)
> If you had to pick one, which would you rather have? (1) good answers quickly on the GWT Developer Forum or (2) extensive, easy-to-use documentation?
I'd go with (2). I've been learning and I have some questions that it
looks like I'll have to ask here, I've been trying to get as much from
the documentation as possible first and foremost.
> What are your 3 favorite examples of technical doc?
1) IETF RFCs : when you need a spec, they are generally thorough and
definitive and easy to find!
2) Sun's Javadoc + Tutorial for Java : thorough, good interface, easy
to skim and easy to search.
3) PostgreSQL : thorough, good details but approachable, good
organization
4) IBM's programming documentation such as "General Programming
Concepts: Writing and Debugging Programs" now available via (somewhat
sluggish and clunky) web interface at http://publib.boulder.ibm.com/infocenter/pseries/v5r3/index.jsp
: thorough, very thorough. But very good organization (search, TOC,
index, skim-able text) so I've often been able to find what I want
quickly which is critical because the volume of data is very large.
Yeah, I know, that's four examples.
> === Use cases, please comment if you disagree or see anything that's missing ===
> <snip>
Looks like a good list. Executing for all those cases
is a tough but worthy goal! :-)
Pavel Byles
Hi everyone,
We're brainstorming about some new documentation approaches as part of an effort to improve the GWT documentation. Your feedback is vitally important to so that we can make the GWT documentation significantly more useful than it is at present. Please answer at least the "High-priority" section and then, if you would be so kind, comment on the use cases below.
The time you take to reply will be a good investment! We'd love to get at least a few dozen replies, if not hundreds!
Thanks,
Bruce
=== High-priority questions in case you don't want to read anything else ===
- What is your screen resolution? (Hypothesis: developers have a much higher average resolution than end users)
- Is your monitor oriented as landscape or portrait? (that is, is it wider than it is tall or vice-versa?)
- How important is each of the following to you? Please rank them in priority order
+ search
+ "related topics" links
+ table of contents
+ index
+ per-topic user-supplied comments
+ speed
+ reading the documentation in a language other than English
- Is javadoc totally sufficient to you for the following...
+ API reference doc
+ Narrative doc, like the stuff that's in the GWT Developer Guide
- If you had to pick one, which would you rather have?
+ good answers quickly on the GWT Developer Forum or
+ extensive, easy-to-use documentation?
- What are your 3 favorite examples of technical doc? (doesn't have to be a web site per se)
=== Use cases, please comment if you disagree or see anything that's missing ===
1) You are brand new to GWT
1.1) You want to get a sample up and running quickly
(everybody likes to see something run)
1.2) You want to get an overview of the breadth of the topics and rough organizations of the concepts and see how they relate to each other
For example, you might ask, "What all can GWT do?"
1.3 ) You start trying to write some new code in GWT, but you haven't memorized anything yet
ahhughes
content).
I've often wanted to make a contribution or even an inline TODO flag
where important things are missing...
> 1.3) You start trying to write some new code in GWT, but you haven't
yanick
all the comments, which IMHO are very much what I think too
(especially the PHP doc, etc.), I would simply point out that not
everyone is using a Tomcat server for JSP dev and all. I personally
use PHP as my server side scripting language at the moment. Not that I
wouldn't enjoy playing with 100% Java Web applications, but that's
where I am bound like many users right now. Some tutorials have been
suggested to run these technologies (GWT + PHP) all together on test
computers, but I was wondering if 1) that matter could be officially
be covered in the doc, and 2) if more examples of best practices with
cross-language AJAX calls could be published for those among us not
using Tomcat servers.
Than again, I am not quite familiar with Tomcat and JSP, a crash
course would also be a good idea (have all that in one site, instead
of jumping around different places to get help.)
Like you said, many people will not see the benefit of playing with
HTML/Javascript/Java and would rather take out Java if they're not
going to have JSPs in their Web pages/application, thus the choice of
other libraries will be more attractive....
In summary, should GWT cover more technologies, and make quick and
easy samples available to play with, as well as better instructions on
how to setup the development computer to run these samples (the idea
of having online streaming videos to watch to has my two thumbs up),
more people will be convinced to stop playing with pure Javascript
only and consider GWT as a real benefit of developing faster Web
application using the power of Java in their projects.
mbracken
(a wider by default hosted browser window would be nice)
The javadoc style api reference is great.
I think better css notes in the javadoc could help. Currently we have
to dig through the code or forum to discover how to style certain
attributes of widgets.
Some performance tips in the dev guide would be helpful.
VR
> - What is your screen resolution? (Hypothesis: developers have a much higher
> average resolution than end users)
>
> - Is your monitor oriented as landscape or portrait? (that is, is it wider
> than it is tall or vice-versa?)
landscape
> - How important is each of the following to you? Please rank them in
> priority order
3) > + search
6) > + "related topics" links
1) > + table of contents
2) > + index
4) > + per-topic user-supplied comments
5) - assuming this is the speed of documentation loadin > + speed
7) > + reading the documentation in a language other than English
> - Is javadoc totally sufficient to you for the following...
Yes > + API reference doc
No > + Narrative doc, like the stuff that's in the GWT Developer Guide
> - If you had to pick one, which would you rather have?
> + good answers quickly on the GWT Developer Forum or
> + extensive, easy-to-use documentation?
- extensive, easy to use documentation
> - What are your 3 favorite examples of technical doc? (doesn't have to be a
> web site per se)
- well commented example code
- the Yahoo YUI website- lots of technical information with many
examples
- javadocs
> === Use cases, please comment if you disagree or see anything that's missing
> ===
> 1) You are brand new to GWT
- no- written several apps by now. Would say I'm an advanced beginner/
intermediate user
> 1.1) You want to get a sample up and running quickly
> (everybody likes to see something run)
- Yes!
> 1.2) You want to get an overview of the breadth of the topics and rough
> organizations of the concepts and see how they relate to each other
> For example, you might ask, "What all can GWT do?"
- Yes.
> 1.3) You start trying to write some new code in GWT, but you haven't
> memorized anything yet
> For example, you might ask, "What's the name of that interface I have to
> implement? Module? No wait, it's called EntryPoint...I think"
- Yes.
> 2) You are using GWT for a real project
- Yes.
> 2.1) You have heard a GWT-specific term, but you don't really know what it
> is and want to learn more
> For example, "What is deferred binding?"
- Yes.
> 2.2) You want to know how GWT deals with a particular subject (e.g. I18N)
> but aren't sure about GWT-specific terminology
> For example, "How can I format this currency value to display to a German
> user?"
- No.
> 2.3) You have an actual problem and need an answer
> For example, "Why am I getting this error message?"
- Yes.
> 2.4) You just want to learn more about GWT by stumbling upon interesting
> topics
> For example, "I wonder if there's a more efficient way to deal with multiple
> static images?"
- Yes.
> 2.5) You want the GWT documentation to be "always up"
> For example, you flip back and forth to it while writing code.
- Yes!
> 3) You are becoming a GWT guru
> 3.1) You want to answer other people's questions by pasting URLs to
> documentation topics
> For example, "The answer to your question is discussed in the GWT Widget
> Developers' guide <here>..."
- Not there yet.
> 3.2) You need to read a lot of detailed exposition about complex topics that
> you'd rather not have to look at normally
> For example, "What are the ordering guarantees of deferred binding
> generators?"
- Yes.
Alexey
> === High-priority questions in case you don't want to read anything else ===
> - What is your screen resolution? (Hypothesis: developers have a much higher
> average resolution than end users)
1152x864
> - Is your monitor oriented as landscape or portrait? (that is, is it wider
> than it is tall or vice-versa?)
landscape
> - How important is each of the following to you? Please rank them in
> priority order
1. table of contents
2. index
3. search
4. per-topic user-supplied comments
5. "related topics" links
6. speed
7. reading the documentation in a language other than English
> - Is javadoc totally sufficient to you for the following...
> + API reference doc
yes
> + Narrative doc, like the stuff that's in the GWT Developer Guide
no
> - If you had to pick one, which would you rather have?
> + good answers quickly on the GWT Developer Forum or
> + extensive, easy-to-use documentation?
extensive documentation
> - What are your 3 favorite examples of technical doc? (doesn't have to be a
> web site per se)
JDK Javadocs, Oracle online books, most man reference pages
> === Use cases, please comment if you disagree or see anything that's missing
> ===
> 1) You are brand new to GWT
> 1.1) You want to get a sample up and running quickly
> (everybody likes to see something run)
I'm normally more interested in know why something basic is running in
order to get a grasp on how the pieces fit in the simplest form. This
may be in the form of getting a sample running, but often times those
kinds of examples are lacking in detail and just have you follow steps
blindly or simply do it in a way divorced from the underpinnings
enough that it's not wholly relevant to you.
> 1.2) You want to get an overview of the breadth of the topics and rough
> organizations of the concepts and see how they relate to each other
> For example, you might ask, "What all can GWT do?"
Perhaps this kind of information is best presented by other users.
Invariably, someone out-there will have a situation somewhat similar
to yours, so it's more effective to look for comments.
> 1.3) You start trying to write some new code in GWT, but you haven't
> memorized anything yet
> For example, you might ask, "What's the name of that interface I have to
> implement? Module? No wait, it's called EntryPoint...I think"
I find I'm reasonably well-versed in the concepts by the time I
actually attempt to write something.
> 2) You are using GWT for a real project
> 2.1) You have heard a GWT-specific term, but you don't really know what it
> is and want to learn more
> For example, "What is deferred binding?"
>
> 2.2) You want to know how GWT deals with a particular subject (e.g. I18N)
> but aren't sure about GWT-specific terminology
> For example, "How can I format this currency value to display to a German
> user?"
With a good table of contents and related topics links, I tend to be
able to find the right place in the documentation fairly quickly.
When not, it tends to be due to misunderstanding the basics.
> 2.3) You have an actual problem and need an answer
> For example, "Why am I getting this error message?"
>
> 2.4) You just want to learn more about GWT by stumbling upon interesting
> topics
> For example, "I wonder if there's a more efficient way to deal with multiple
> static images?"
>
> 2.5) You want the GWT documentation to be "always up"
> For example, you flip back and forth to it while writing code.
>
> 3) You are becoming a GWT guru
> 3.1) You want to answer other people's questions by pasting URLs to
> documentation topics
> For example, "The answer to your question is discussed in the GWT Widget
> Developers' guide <here>..."
>
Transplant
On Sep 13, 8:31 am, "Bruce Johnson" <br...@google.com> wrote:
> Hi everyone,
>
ersa?)
>
> - How important is each of the following to you? Please rank them in
> priority order
+ search
+ table of contents
+ index
+ "related topics" links
+ speed
+ per-topic user-supplied comments
+ reading the documentation in a language other than English
> - Is javadoc totally sufficient to you for the following...
+ API reference doc
The format is sufficient, but the content is a little bit thin -
example:
Class docs for ScrollPanel:
"A simple panel that wraps its contents in a scrollable area."
If the javadocs were fleshed out with a little more usable reference
information, the format would certainly suffice for me, and, I think,
most developers.
+ Narrative doc, like the stuff that's in the GWT Developer Guide
I don't think javadoc is sufficient for this - it doesn't lend itself
well to narrative learning trails or exploration of examples.
>
> - If you had to pick one, which would you rather have?
> + good answers quickly on the GWT Developer Forum or
> + extensive, easy-to-use documentation?
I'd rather have the documentation. Forums are good for short term
issues that cannot be found in regular documentation, but forums and
wikis suffer from:
1) bad searchability (too many useless search hits)
2) stale information (is this bug workaround still relevant?)
3) incompleteness (that api option is very close to what I need - what
are the others?)
4) portability (can't use it if you're not online)
> === Use cases, please comment if you disagree or see anything that's missing
> ===
Missing: I want to see where <some-misbehaving-feature> is implemented
in the code. Direct links to the code base from the documentation can
be extremely helpful.
malcolm...@gmail.com
> - What is your screen resolution? (Hypothesis: developers have a much higher
> average resolution than end users)
>
> - Is your monitor oriented as landscape or portrait? (that is, is it wider
> than it is tall or vice-versa?)
>
> - How important is each of the following to you? Please rank them in
> priority order
> + search
> + table of contents
> + index
> + speed
2 Table of contents
3 Index
4 per-topic user-supplied comments
5 speed
>
> - Is javadoc totally sufficient to you for the following...
> + API reference doc
> + Narrative doc, like the stuff that's in the GWT Developer Guide
Would like more examples. For instance, how to add JUnit testing
to an existing project. I still haven't worked out how, and I really
need to.
I know how to use the tools, but I keep striking chicken-and-egg
problems.
I'm using Eclipse and there's no difficulty getting JUnit tests
working with
non-GWT-UI objects.
>
> - If you had to pick one, which would you rather have?
> + good answers quickly on the GWT Developer Forum or
> + extensive, easy-to-use documentation?
Extensive, easy to use documentation.
>
> - What are your 3 favorite examples of technical doc? (doesn't have to be a
> web site per se)
1 JUnit Cookbook
2 Thinking In Java
3 Refactoring To Patterns
>
> === Use cases, please comment if you disagree or see anything that's missing
> ===
> 1) You are brand new to GWT
> 1.1) You want to get a sample up and running quickly
> (everybody likes to see something run)
I am fairly new to GWT. My last project was a very successful Google
Maps app.
My current project is a GWT app. I have little difficulty getting it
working and showing
people -- they are incredibly impressed by the speed of the app. But
I'd like to demonstrate
JUnit testing, which I haven't got working yet.
>
> 1.2) You want to get an overview of the breadth of the topics and rough
> organizations of the concepts and see how they relate to each other
> For example, you might ask, "What all can GWT do?"
>
> 1.3) You start trying to write some new code in GWT, but you haven't
> memorized anything yet
> For example, you might ask, "What's the name of that interface I have to
> implement? Module? No wait, it's called EntryPoint...I think"
>
> 2) You are using GWT for a real project
> 2.1) You have heard a GWT-specific term, but you don't really know what it
> is and want to learn more
> For example, "What is deferred binding?"
I am using GWT for a real project, and I want to make sure it all
works okay,
so I can get to do another few projects in GWT.
>
> 2.2) You want to know how GWT deals with a particular subject (e.g. I18N)
> but aren't sure about GWT-specific terminology
> For example, "How can I format this currency value to display to a German
> user?"
>
> 2.3) You have an actual problem and need an answer
> For example, "Why am I getting this error message?"
>
> 2.4) You just want to learn more about GWT by stumbling upon interesting
> topics
> For example, "I wonder if there's a more efficient way to deal with multiple
> static images?"
>
> 2.5) You want the GWT documentation to be "always up"
> For example, you flip back and forth to it while writing code.
>
> 3) You are becoming a GWT guru
> 3.1) You want to answer other people's questions by pasting URLs to
> documentation topics
> For example, "The answer to your question is discussed in the GWT Widget
> Developers' guide <here>..."
>
> 3.2) You need to read a lot of detailed exposition about complex topics that
> you'd rather not have to look at normally
> For example, "What are the ordering guarantees of deferred binding
> generators?"
I'm a bit obsessed with JUnit right now. I want to demonstrate how
productive JUnit is.
The GWT team has gone to great lengths to integrate JUnit into GWT.
But there isn't
enough documentation on the web or in the Hanson & Tacy book to get me
up and running.
Once I have it figured out, I'd be happy to try my hand at a guru
description of how to get
it running in Eclipse. By the time I get it running, I'll be a guru!
Mal.
Ian Bambury
=== High-priority questions in case you don't want to read anything else ===
- What is your screen resolution? (Hypothesis: developers have a much higher average resolution than end users)
- Is your monitor oriented as landscape or portrait? (that is, is it wider than it is tall or vice-versa?)
- How important is each of the following to you? Please rank them in priority order
+ search
+ "related topics" links
+ table of contents
+ index
+ per-topic user-supplied comments
+ speed
+ reading the documentation in a language other than English
- Is javadoc totally sufficient to you for the following...
+ API reference doc
+ Narrative doc, like the stuff that's in the GWT Developer Guide
- If you had to pick one, which would you rather have?
+ good answers quickly on the GWT Developer Forum or
+ extensive, easy-to-use documentation?
- What are your 3 favorite examples of technical doc? (doesn't have to be a web site per se)
=== Use cases, please comment if you disagree or see anything that's missing ===
1) You are brand new to GWT
1.1) You want to get a sample up and running quickly
(everybody likes to see something run)
1.2) You want to get an overview of the breadth of the topics and rough organizations of the concepts and see how they relate to each other
For example, you might ask, "What all can GWT do?"
1.3 ) You start trying to write some new code in GWT, but you haven't memorized anything yet
For example, you might ask, "What's the name of that interface I have to implement? Module? No wait, it's called EntryPoint...I think"
2) You are using GWT for a real project
2.1) You have heard a GWT-specific term, but you don't really know what it is and want to learn more
For example, "What is deferred binding?"
2.2) You want to know how GWT deals with a particular subject (e.g. I18N) but aren't sure about GWT-specific terminology
For example, "How can I format this currency value to display to a German user?"
2.3) You have an actual problem and need an answer
For example, "Why am I getting this error message?"
2.4) You just want to learn more about GWT by stumbling upon interesting topics
For example, "I wonder if there's a more efficient way to deal with multiple static images?"
2.5) You want the GWT documentation to be "always up"
For example, you flip back and forth to it while writing code.
3) You are becoming a GWT guru
3.1) You want to answer other people's questions by pasting URLs to documentation topics
For example, "The answer to your question is discussed in the GWT Widget Developers' guide <here>..."
3.2) You need to read a lot of detailed exposition about complex topics that you'd rather not have to look at normally
For example, "What are the ordering guarantees of deferred binding generators?"
--
Ian
--------------------------------------------
http://examples.roughian.com
--------------------------------------------
Gerard Toonstra
> - What is your screen resolution?
1680x1050 landscape
+ table of contents
+ search
+ speed
+ per-topic user-supplied comments
+ "related topics" links
+ index
+ reading the documentation in a language other than English
> - Is javadoc totally sufficient to you for the following...
docs are ok, but examples could be larger and a bit more clear.
> - If you had to pick one, which would you rather have?
> + good answers quickly on the GWT Developer Forum
> - What are your 3 favorite examples of technical doc? (doesn't have to be a
> web site per se)
* Like the GWT doc, but mixed with more examples and in more detail.
* JavaDoc
> 3) You are becoming a GWT guru
> 3.1) You want to answer other people's questions by pasting URLs to
> documentation topics
> For example, "The answer to your question is discussed in the GWT Widget
> Developers' guide <here>..."
At some point. Also useful for blogs.
> 3.2) You need to read a lot of detailed exposition about complex topics that
> you'd rather not have to look at normally
> For example, "What are the ordering guarantees of deferred binding
> generators?"
Could be handy for extending GWT.
It might be useful as well to include design patterns if they so far
exist. I found that especially in the beginning, code looked a lit
foreign because it depended heavily on callbacks and the likes.
Also, applications often have very similar problems and these are not
extensively detailed on the site. Think of issues like:
* How to solve access control problems, or should you even use GWT?
* GWT in large applications.
* Design patterns applied to GWT.
* What are things to be designing and thinking about before you write
your first module? (history support and how, progress indicators,
load indicators?).
But maybe these are topics in the book that was published, in which
case it's a good idea to refer to the book for those practices.
G>
Tristan
> - What is your screen resolution? (Hypothesis: developers have a much higher
> average resolution than end users)
>
1280x1024
> - Is your monitor oriented as landscape or portrait? (that is, is it wider
> than it is tall or vice-versa?)
landscape
>
> - How important is each of the following to you? Please rank them in
> priority order
> + search
> + "related topics" links
> + table of contents
> + index
> + per-topic user-supplied comments
> + speed
> + reading the documentation in a language other than English
>
search
speed
"related topics" links
index
per-topic user-supplied comments
table of contents
> - Is javadoc totally sufficient to you for the following...
> + API reference doc
javadoc in the IDE works great