December 2014 Developer's Poll

Use this forum for polls.

How would you rate the quality of the Embarcadero documentation on C++Builder?

a. Excellent
No votes
b. Good
c. Average
d. Poor
Total votes: 42

User avatar
BCBJ Editor and Admin
BCBJ Editor and Admin
Posts: 285
Joined: Wed May 26, 2004 11:25 pm
Location: Stillwater, OK, USA

December 2014 Developer's Poll

Post by Damon »

I would like to hear others' opinions regarding the quality of the C++Builder reference documentation (help files). If you need something to compare against, consider the Windows API help files or Visual Studio help files.

Damon Chandler
C++Builder Developer's Journal
Posts: 140
Joined: Sat Nov 29, 2014 8:02 pm
Location: Las Vegas

Re: December 2014 Developer's Poll

Post by smd »

[1] Indexing of the help information is awful, horrible.

[2] The dreaded:
Embarcadero Technologies does not currently have any additional information. Please help us document this topic by using the Discussion page!
They do not know how their own stuff works?

[3] Multiple sub-links just to display a page with only one or a few sentences.

Unfortunately, the kids designing stuff these days have no concept how to write documentation, not a clue, completely ignorant of the process.

For a given topic, a page should exist such that I can simply press PRINT (once) to print out all information about that item or function. I should not need to print out a digital document, but every specific topic should have a page to do such. Especially considering that the document is digital, where zero cost exists for adding pages (as compared to a hard copy that requires more paper), ALL information about an item should be inclusive on ONE page. Repeat information as necessary for a topic instead of linking.

Links to additional information are OK as long as that information is a side topic, or information about related operations. But for a specific operation, ALL information required for that operation should be gathered in one place.

Links should be designed like a proper outline. Think of the table of contents at the beginning of a book. The current documentation is way too fragmented. It needs to be coalesced into a simpler tree of information.

When I press F1 for help on the cursor item, it should take me to a bookmark on a details page, not a page that I then have to click several links and still not get to the details page.

[4] Most important is formatting that page for useability. This means addressing the needs of the audience.

The new user who may not be familiar with the concepts being presented. A quick overview with an example helps tremendously.

The intermediate user who has some familiarity, but needs more information about specifics. What is most aggravating is that ALL, and I mean ALL. Let me say it again ALL, options for a given function or operation should be presented in a table ON THAT PAGE. Let me say that one more time as Embarcadero is wholly clueless about this concept. ALL OPTIONS FOR A FUNCTION SHALL BE PRESENTED ON ONE PAGE.

The advanced user that just needs a quick reference about parameters, options, format, etc...

Ugh, I can go on for much longer, but I have real work to get back to.