Page 1 of 1

December 2014 Developer's Poll

PostPosted: Mon Jan 05, 2015 11:19 pm
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.

Cheers,

Re: December 2014 Developer's Poll

PostPosted: Mon Jan 12, 2015 5:30 am
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.