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,
December 2014 Developer's Poll
2 posts
• Page 1 of 1
December 2014 Developer's Poll
by Damon » Mon Jan 05, 2015 11:19 pm
-
Damon - BCBJ Editor and Admin
- Posts: 285
- Joined: Wed May 26, 2004 11:25 pm
- Location: Stillwater, OK, USA
Re: December 2014 Developer's Poll
by smd » Mon Jan 12, 2015 5:30 am
[1] Indexing of the help information is awful, horrible.
[2] The dreaded:
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.
[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
Scott
- smd
- BCBJ Guru
- Posts: 132
- Joined: Sat Nov 29, 2014 8:02 pm
- Location: Las Vegas
2 posts
• Page 1 of 1
Who is online
Users browsing this forum: No registered users and 2 guests