[cdt-dev] Re: C++ Developer's User Guide review comments

[Tanya-Marise De Sousa <tdesous@xxxxxxxxxx>]

Thanks very much for your comments. I will do my level best to recover all of the comments I have received thus far to make the October 1 documentation and code freeze date.

Feedback not recovered for 1.2, will be recovered, as applicable for CDT 2.0.

Regards,
Tanya-Marise de Sousa           
Information Development
Rational Software
IBM Software Group 
613.591.7931
~~~~~~~~~~~~~~~~~~

"Jodi Conard" <JCONARD@xxxxxxxxxx> 09/16/2003 03:57 PM

To:        Tanya-Marise De Sousa/Ottawa/IBM@IBMCA         cc:        <cdt-dev@xxxxxxxxxxx>, <cdt-doc-dev@xxxxxxxxxxx>         Subject:        C++ Developer's User Guide review comments

Below are C++ Developer's User Guide review comments for your consideration as you continue developing this user guide. The premise of my comments are from the perspective of a new Eclipse user and assumes that the C++ Development User Guide is the first help content the user accesses in Eclipse.

General Online Help Book Comments:

(1) The question index in the JDT Plug-In Developers Guide and Platform Plug-In Developer Guide is excellent and a great venue for application-type content.

(2) Seems there should be some special font treatment for "Notes" and "Important Information" so the user clearly sees the information and it stands out from the other  content.

General  C++ Development User Guide Comments:

(1)  I can see the table format at the outset of a topic provides a quick way to access information, but I think introductory paragraphs and hyperlinks would be more effective. If you like the table format, I would suggest more introductory information before the table.

(2) I suggest more screen shots to visually display the procedures you have in the tutorial and other topics.
(3) Perhaps references to any topic in the Toolbench User Guide should be a hyperlink.

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

Topic Title: Getting Started

Comment on this topic:
I would have the first getting started page contain the content in the CDT Overview. I suggest an opening sentence that suggests a new user see the Toolbench User Guide (with a hyperlink) for an overview of the Eclipse environment.  I would include a topic list with some of the following topics found in the Toolbench User Guide.

(1) Eclipse Environment Overview (Toolbench User Guide)
(2) Perspective (Toolbench User Guide)
(3) Concept (Toolbench User Guide)
(4) Task (Toolbench User Guide)
(5) Reference (Toolbench User Guide)
(6) User Interface Reference (C++ Development User Guide)

Perhaps the "What's New" topic should go under the "Reference" topic.  

--------------------------------
Topic Title: C/C++ Development perspective

Comment on this topic:
I suggest making the bulleted items a topic list. This makes it easier for the user to get to the information.

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

Topic Title: Legacy Code

Comment on this topic:
I suggest changing the topic to "Importing Code" to better match the information provided.

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

Topic Title: How the CDT associates projects

Comment on this topic:

I suggest this reference be a hyperlink...
see Reference > User interface information > Development environment > Local history in the Workbench User Guide.
----------------------------------------

Topic Title: Creating your C++ File

Comment on this topic:

In step 2, I think it should read "folder" name instead of "file" name

----------------------------------------
Topic Title: Creating standard make C or C++ projects

Comment on this topic:

I thought this topic should be introduced sooner --- perhaps an overview in the Getting Started topic with links to more details in this section.

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

Regards,

Jodi

...........................................................
Jodi Conard
Documentation Supervisor
Altera Santa Cruz Technology Center  
(408) 544-8523
jconard@xxxxxxxxxx
SCTC Updates: http://sc-web
...........................................................