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
0
No votes
b. Good
5
12%
c. Average
15
36%
d. Poor
22
52%
 
Total votes : 42

December 2014 Developer's Poll

Postby Damon » Mon Jan 05, 2015 11:19 pm

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.

Cheers,
Damon Chandler
Editor-in-Chief
C++Builder Developer's Journal
http://bcbjournal.com
User avatar
Damon
BCBJ Editor and Admin
BCBJ Editor and Admin
 
Posts: 285
Joined: Wed May 26, 2004 11:25 pm
Location: Stillwater, OK, USA

Re: December 2014 Developer's Poll

Postby smd » Mon Jan 12, 2015 5:30 am

[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.
-----------------------------
Scott
smd
BCBJ Guru
BCBJ Guru
 
Posts: 130
Joined: Sat Nov 29, 2014 8:02 pm
Location: Las Vegas


Return to Polls

Who is online

Users browsing this forum: No registered users and 1 guest

cron