[cdt-doc-dev] C/C++ Development User Guide: part 2 of 2

[Mike Behm <mbehm@xxxxxxxxxx>]

Again, the documentation is coming along very well. There are just a few 
small suggestions for you.


Best regards,
Mike


C/C++ Development User Guide
============================

Concepts > C/C++ perspective
----------------------------
 -"A perspective is a task-oriented configuration
  of the Eclipse workbench that provides a graphical
  development environment for C and C++ developers."

  If you are defining the term 'perspective', it
  would be better to be more generic:
   "A perspective is a task-oriented configuration
   of the Eclipse workbench that provides a graphical
   development environment for developers."

  Alternatively, if you are describing just this
  perspective, you could say:
  "This perspective is a task-oriented configuration
  of the Eclipse workbench that provides a graphical
  development environment for C and C++ developers."

  You could apply italics to terms that are being
  defined:
  "<p>The term <i>Workbench</i> refers to..."


Concepts > C/C++ projects
-------------------------
 -Typo: "...a project, the a record..."
 -You might want to say that the workspace is a directory
  and say where it is located.


Project file views
------------------
 -Would it be useful to define what a context menu is?


Outline view
------------
 -"double-click main() in Outline view."
  (Add "the" before "Outline".)


Code templates
--------------
 -"Templates are a structured description of coding
  patterns that reoccur in source code."
  That's true, but I'm just a simple country boy, so
  I'd suggest:
  "Templates are sections of code that occur frequently
  enough that you would like to be able to insert them
  with a few keystrokes."


Function information
--------------------
 -The TOC reference for this is "Hover Help".
 -The "mouse curser" should be "mouse cursor".


Build overview
--------------
 -"The CDT can perform makes automatically or you can
  create your own make file."
  This sentence is comparing two different ideas:
    -The CDT creates a make file that will build
     simple projects or you can create your own
     makefile.
    -The CDT can perform makes automatically whenever
     you save a project file, or you can build your
     projects manually.
 -"Build every component from scratch." This might be
  too colloquial for some readers.
 -Build preferences: you should add where these preferences
  are controlled.


Debug information
-----------------
 -I believe this is describing the Debug perspective rather
  than the Debug view.
 -Typo: "...about expressions in the Expressions view.b"


Displaying C/C++ file members
-----------------------------
 -What is a file member?


Creating a managed-make project
-------------------------------
 -You could add a definition of what a managed-make project is
  ("A managed make project is one for which Eclipse creates and
   manages the make file. To create a managed-make project:").


Creating a managed make project
-------------------------------
 -"Files are edited in the C/C++ editor that appears to the
  immediate right of the C/C++ Projects view."
  You might want to say that when you create a file in the CDT,
  it automatically opens in the C/C++ editor, but avoid mentioning
  where that pane appears (as the panes can be moved around).


Creating a makefile
-------------------
 -It might be better to open with the conditions under which you
  need to create a makefile.

    If you have not created a Managed Make C++ project, you need
    to write your own makefile.

    To create your makefile:
    ...instructions (ideally including an annotated sample)...

    Output from make displays in the C-Build view. Makefile
    actions display in the Make Targets view.

  You could also add a note telling the reader whether or not they
  are able to edit the makefile in a Managed Make C++ project.


Using Content Assist to finish function names
---------------------------------------------
 -The instructions begin with the reader typing the first letter
  of a function in the editor. Rather than suggest that the reader
  moves to the mouse to right-click and choose Content Assist, you
  could give the keyboard shortcut and give the context menu option
  as a note.


Shifting lines of code to the left or right
-------------------------------------------
 -Can you configure the number of spaces spanned by a tab character?