<div>There was an ongoing dialogue on a Borland new Group on this where the head of the documentation team came in and said that they were going to get the help right in D2006, however it looks like some of the older posts have been removed (bit of ethnic cleansing it seems).
</div>
<div> </div>
<div>The group has some useful suggestions and insights <a href="news://borland.public.delphi.documentation">news://borland.public.delphi.documentation</a></div>
<div> </div>
<div>Paul<br><br> </div>
<div><span class="gmail_quote">On 07/05/06, <b class="gmail_sendername">Dave O'Brien</b> <<a href="mailto:dave@iccs.co.nz">dave@iccs.co.nz</a>> wrote:</span>
<blockquote class="gmail_quote" style="PADDING-LEFT: 1ex; MARGIN: 0px 0px 0px 0.8ex; BORDER-LEFT: #ccc 1px solid">I find the D2005 help to be particularly unhelpful. Some of the time,<br>pressing F1 on a standard keyword will come up with something useful
<br>then doing the same thing again (within minutes) will come up with<br>nothing. This appears to be random to me.<br><br>The D2005 format is also somewhat annoying. I prefer the "ancient"<br>format. I also prefer a consistent answer when I ask for something...
<br><br>David O'Brien<br>ICCS<br>P.O Box 1116<br>Palmerston North<br>027 442 1037<br>Computer sales and support services<br>Custom software design<br><br>-----Original Message-----<br>From: <a href="mailto:delphi-bounces@ns3.123.co.nz">
delphi-bounces@ns3.123.co.nz</a> [mailto:<a href="mailto:delphi-bounces@ns3.123.co.nz">delphi-bounces@ns3.123.co.nz</a>]<br>On Behalf Of John Bird<br>Sent: Saturday, 6 May 2006 3:29 p.m.<br>To: 'Kyley Harris'; 'NZ Borland Developers Group - Delphi List'
<br>Subject: [DUG] Delphi Help<br><br>I am not a pugnacious person, but this is one topic I would start a<br>fight<br>over.<br><br>A little more about the Unix Help - it has a standard format in a known<br>directory stucture. It covers many different areas from system calls to
<br>3rd<br>party addon products and part of the automatic standard system is to<br>scan<br>all the help and build<br>A database summary of the help, commands, keywords from the help, and<br>which<br>sections it is in.<br>
<br>There are two commands for interrogating this summary database whatis<br>and<br>apropos<br><br>whatis apropos for instance prints a brief summary of the apropos<br>command, which section the full help is<br>apropos whatis searches the keywords and reports on anything similar
<br>to<br>whatis, and where there is more help.<br><br>Even the Delphi 5 Help was split into Dephi Help and Delphi Win32 SDK,<br>and<br>you could not normally search both at once.<br>Windows Help systems have an index, but in probably half the cases it is
<br>useless as the poor programmer does not know which word he is searching<br>for.<br>Saying the help system is not meant to provide this total is a cop out<br>in my<br>mind, its like half the index is missing. When you come across a Help
<br>that<br>can be used from any direction you are so grateful and should learn the<br>lesson! The larger the system the more important this is, as<br>programmers<br>hold less and less of it in memory (so to speak)<br><br>
Fortunately there is a way around this, but it should not be needed:<br>GIYF.<br>(Google GIYF if you don't know what it is)<br><br>How many times have I looked up topics like<br><br>Delphi IDE keyboard shortcuts<br>Delphi File i/o
<br><br>When writing application help files for instance, most of the ones I had<br>to<br>do with were entirely full of<br><br>"How to do....." entries in the index: I quote a example. The entire<br>manual is like this:
<br><br>How to input debtors transactions (No sales analysis) 48<br>How to input debtors transactions (With sales analysis) 52<br>How to generate debtors transactions (No sales analysis) 60<br>How to generate debtors transactions (With sales analysis) 64
<br>How to void debtor transactions 69<br>How to post transactions 71<br>How to post external debtors transactions 72<br>How to consolidate ship-to bill-to accounts 73
<br>How to produce debtors statements 75<br>How to produce a debtors trial balance 82<br>How to age a debtors ledger 88<br>How to create a debtors branch file 91
<br>How to create a sales ledger 92<br>How to maintain sales ledger budgets 96<br>How to maintain sales ledger descriptions 98<br>How to produce sales ledger printouts 101
<br><br>John<br><br>-----Original Message-----<br>From: Kyley Harris [mailto:<a href="mailto:kyley@harrissoftware.com">kyley@harrissoftware.com</a>]<br>Sent: Saturday, 6 May 2006 2:53 p.m.<br>To: <a href="mailto:johnkbird@paradise.net.nz">
johnkbird@paradise.net.nz</a>; NZ Borland Developers Group - Delphi List<br>Subject: RE: [DUG] Naming your code and Delphi Help<br><br><br>What you are talking about it Training, not help files. Helpfiles from a<br>technical perspective tend to be dry. They are informing a knowledgeable
<br>person of the abilities of the tool. If you got a help file for a hammer<br>it<br>is going to outline all the qualities of the hammer, its head, density,<br>shape. It will explore the style of nail it is best suited for, or the
<br>wooden pegs it is designed to pummel in. The help file for a hammer is<br>not<br>going to have a section: How to best build a garage using this hammer.<br>You<br>go to school to learn such practices.<br><br>I think you are expecting too much from the "help". I agree that the new
<br>help files using the Microsoft help engine is absolute shit. When I<br>tried<br>2005 I found it slow and crappy. The old style help system was far more<br>preferable.<br><br>In saying that however. The example driven approach of the T-SQL help
<br>file<br>for MSSQL is invaluable. So I can see what you are getting at.<br><br><br>>I meant he was a superb programmer seriously and also with a dry sense<br>of<br>>humour - his software worked fantastically, but in no way a team player
<br>in<br>>making it easy for anyone to do anything with his code afterwards...<br><br>And I seriously meant that if no-one could understand what he did and he<br>isn't a team player, then by definition he cant be a superb programmer,
<br>merely a skilled technical person.<br><br>-----Original Message-----<br>From: <a href="mailto:delphi-bounces@ns3.123.co.nz">delphi-bounces@ns3.123.co.nz</a> [mailto:<a href="mailto:delphi-bounces@ns3.123.co.nz">delphi-bounces@ns3.123.co.nz
</a>]<br>On Behalf Of John Bird<br>Sent: Saturday, 6 May 2006 10:27 a.m.<br>To: 'NZ Borland Developers Group - Delphi List'<br>Subject: RE: [DUG] Naming your code and Delphi Help<br><br>I meant he was a superb programmer seriously and also with a dry sense
<br>of<br>humour - his software worked fantastically, but in no way a team player<br>in<br>making it easy for anyone to do anything with his code afterwards...<br><br>Personally I have tended to rely also on help files (which discuss the
<br>sorts<br>of operations users will follow), and software product descriptions,<br>which<br>usually should have a good description of how a system is put together.<br><br>HELP SYSTEMS<br>============<br>Can I put in my hobby horse about help systems, which Delphi needs to do
<br>something about, as well as anyone using any large complex system: All<br>such<br>systems need more than a detailed description of what all the menu<br>entries<br>do, and detailed descriptions of each function. They also need to have
<br>a<br>different view into the help of guiding a new user who doesn't know<br>where to<br>look or which commmands to use. The Delphi 5 Help was better in this<br>than<br>the D2006 Help (which has gone to more MS layouts).
<br><br>Example:<br>In Delphi when I wanted to start doing a lot with file i/o I wanted to<br>read<br>up the best practice ways of doing this, and see what the main functions<br>are. In the Delphi 5 Help I at least found there are 3 main ways of
<br>doing<br>file i/o, (1-Text File and untyped files, 2-TFileStream, 3-Windows<br>Handles<br>and Win32 API). However an indepth description of why there are 3 ways<br>and<br>the advantages of each and info on which approach the typical VCL
<br>components<br>use (eg in loadfromfile methods) would have been useful - I had to trawl<br>though each to find which looked the most thoroughly implmented and ask<br>others...<br><br>In my mind exploring a help system I should be able to find topics like
<br><br>What grids are best to use,<br>Best ways to do File i/o<br>Overview of using DataAware controls<br>Main points for using the IDE<br>Power features in the IDE<br><br>There is NO way to find help on those topics in the IDE. It's a mark
<br>against getting a RAD system when you can't find the answer because you<br>don't know what question to ask ie what word to search for.<br><br>I was spoiled in early days by the help on Unix systems - despite its<br>reputation for unfriendliness the help system had one feature I have
<br>yearned<br>for everywhere else: the apropos command, sort of like a Google on the<br>help.<br><br>You could type for instance "apropos network" or "apropos printing" or<br>"apropos /etc/passwd" and it would list all the help topics and areas
<br>that<br>had information on this, in great concise detail. The integrated Help<br>system on a Unix machine can all be searched by one command (packages<br>all<br>installed their manuals into the systems help folders).
<br><br>John<br><br><br>-----Original Message-----<br>From: <a href="mailto:delphi-bounces@ns3.123.co.nz">delphi-bounces@ns3.123.co.nz</a> [mailto:<a href="mailto:delphi-bounces@ns3.123.co.nz">delphi-bounces@ns3.123.co.nz
</a>]<br>On<br>Behalf Of Kyley Harris<br>Sent: Friday, 5 May 2006 4:28 p.m.<br>To: NZ Borland Developers Group - Delphi List<br>Subject: RE: [DUG] Naming your code<br><br><br>You beat me to it. I agree with most of John's statements about headers
<br>etc.<br>and why you cant trust source control unless you will stick with it for<br>life<br>on the same system.<br><br>But Superb Programmer? Perhaps you meant Intelligent Person? There are<br>plenty of Geniuses, engineers, mathematicians etc, who all code because
<br>it<br>helps their other jobs. Programming is a role itself, that does not<br>require<br>skills in all these other areas. A Suberb programmer should in the<br>least:<br><br>Write clean consistent code.<br>Write self documenting code.
<br>Also write supplementary comments regarding complex self-documenting<br>code.<br>Understand the goal, before starting the task.<br><br>A Suberb programmer, does not need to know maths etc. This is all<br>available<br>
in books and specs. A Suberb programmer knows how to take all the bits<br>and<br>pieces and turn it into maintainable, clean, bug free software. I am<br>guessing that most Delphi group people are a mixture of Programmer,<br>
Self-manager, etc. Not everyone works corporate. But its important to<br>distinguish the skill of programming, aside from the skills of other<br>mixed<br>roles.<br><br>-----Original Message-----<br>From: <a href="mailto:delphi-bounces@ns3.123.co.nz">
delphi-bounces@ns3.123.co.nz</a> [mailto:<a href="mailto:delphi-bounces@ns3.123.co.nz">delphi-bounces@ns3.123.co.nz</a>]<br>On Behalf Of Todd Martin<br>Sent: Friday, 5 May 2006 3:49 p.m.<br>To: <a href="mailto:johnkbird@paradise.net.nz">
johnkbird@paradise.net.nz</a>; NZ Borland Developers Group - Delphi List<br>Subject: Re: [DUG] Naming your code<br><br>I assume you're joking. That's not my idea of 'superb programming'.<br><br>> The extreme example was one package where the variables had different
<br>names<br>> and declarations from one program to another, the programmer concerned<br>wrote<br>> not one single comment in his code, and liked naming variables with<br>names<br>> like B320 B330 B340 etc. He was a superb programmer who believed code
<br><br>> should be read to find what it does, and also liked reading object<br>files<br>> directly.....if you are lucky you wouldn't be maintaining his code, it<br>was<br>> hard to improve in all senses.<br>>
<br>> John<br>><br>><br>> -----Original Message-----<br>> From: <a href="mailto:delphi-bounces@ns3.123.co.nz">delphi-bounces@ns3.123.co.nz</a><br>[mailto:<a href="mailto:delphi-bounces@ns3.123.co.nz">delphi-bounces@ns3.123.co.nz
</a>]<br>On<br>> Behalf Of Richard Vowles<br>> Sent: Friday, 5 May 2006 12:53 p.m.<br>> To: NZ Borland Developers Group - Delphi List<br>> Subject: RE: [DUG] Naming your code<br>><br>><br>> It should be in the version control check-in anyway so you know who to
<br><br>> blame. The only reason it isn't in my code is I can't be bothered<br>putting<br>it<br>> there. It is there on templated code.<br>><br>> (a dedicated subversion user).<br>><br>> How about people change subject lines to match what we are talking
<br>about.<br>> ---<br>> Richard Vowles, Solutions Architect, Borland New Zealand<br>> email: <a href="mailto:richard.vowles@borland.com">richard.vowles@borland.com</a><br>> phone: +64-9-9184573<br>> cell: +64-21-467747
<br>> other: MSN <a href="mailto:richard.vowles@borland.com">richard.vowles@borland.com</a>, skype: rvowles<br>> blog: <a href="http://www.usergroup.org.nz/blogs/selectBlog.html?id=39769">http://www.usergroup.org.nz/blogs/selectBlog.html?id=39769
</a><br>><br>> -----Original Message-----<br>> From: <a href="mailto:delphi-bounces@ns3.123.co.nz">delphi-bounces@ns3.123.co.nz</a><br>[mailto:<a href="mailto:delphi-bounces@ns3.123.co.nz">delphi-bounces@ns3.123.co.nz
</a>]<br>> On Behalf Of Kyley Harris<br>> Sent: Thursday, 4 May 2006 11:42 p.m.<br>> To: NZ Borland Developers Group - Delphi List<br>> Subject: RE: [DUG] In case you're interested (or buy stuff)<br>><br>> Correct. Many companies that rely on contractors to fulfill work do
<br>not<br>want<br>> temp employess, etc to see a name, and go tell the competition who<br>they<br>> should contact for good design work. So in that case it is valid to<br>request<br>> unsigned work. If you really want to assert that you wrote something.
<br>Get<br>a<br>> reference in writing on letterhead that cannot be disputed by future<br>> managers, employees etc. Get the letter to state unequivocally what<br>input<br>> you had such as design, implementation, delployment. NEVER rely on an
<br>> interviewer calling someone. I make a point of providing no verbal<br>> references unless that person giving the ref would die for me, or<br>close :D<br>><br>> _______________________________________________
<br>> Delphi mailing list<br>> <a href="mailto:Delphi@ns3.123.co.nz">Delphi@ns3.123.co.nz</a> <a href="http://ns3.123.co.nz/mailman/listinfo/delphi">http://ns3.123.co.nz/mailman/listinfo/delphi</a><br>><br>><br>
> __________ NOD32 1.1461 (20060329) Information __________<br>><br>> This message was checked by NOD32 antivirus system.<br><a href="http://www.eset.com">http://www.eset.com</a><br>><br>><br>><br>> _______________________________________________
<br>> Delphi mailing list<br>> <a href="mailto:Delphi@ns3.123.co.nz">Delphi@ns3.123.co.nz</a> <a href="http://ns3.123.co.nz/mailman/listinfo/delphi">http://ns3.123.co.nz/mailman/listinfo/delphi</a><br>><br>><br>
><br>> --<br>> No virus found in this incoming message.<br>> Checked by AVG Free Edition.<br>> Version: 7.1.385 / Virus Database: 268.5.1/327 - Release Date:<br>28/04/2006<br>><br><br><br><br>--<br>No virus found in this outgoing message.
<br>Checked by AVG Free Edition.<br>Version: 7.1.385 / Virus Database: 268.5.1/327 - Release Date:<br>28/04/2006<br><br>_______________________________________________<br>Delphi mailing list<br><a href="mailto:Delphi@ns3.123.co.nz">
Delphi@ns3.123.co.nz</a> <a href="http://ns3.123.co.nz/mailman/listinfo/delphi">http://ns3.123.co.nz/mailman/listinfo/delphi</a><br><br><br><br>_______________________________________________<br>Delphi mailing list<br><a href="mailto:Delphi@ns3.123.co.nz">
Delphi@ns3.123.co.nz</a> <a href="http://ns3.123.co.nz/mailman/listinfo/delphi">http://ns3.123.co.nz/mailman/listinfo/delphi</a><br><br><br>__________ NOD32 1.1461 (20060329) Information __________<br><br>This message was checked by NOD32 antivirus system.
<a href="http://www.eset.com">http://www.eset.com</a><br><br><br><br>_______________________________________________<br>Delphi mailing list<br><a href="mailto:Delphi@ns3.123.co.nz">Delphi@ns3.123.co.nz</a> <a href="http://ns3.123.co.nz/mailman/listinfo/delphi">
http://ns3.123.co.nz/mailman/listinfo/delphi</a><br><br><br><br><br>__________ NOD32 1.1461 (20060329) Information __________<br><br>This message was checked by NOD32 antivirus system. <a href="http://www.eset.com">http://www.eset.com
</a><br><br><br><br>_______________________________________________<br>Delphi mailing list<br><a href="mailto:Delphi@ns3.123.co.nz">Delphi@ns3.123.co.nz</a><br><a href="http://ns3.123.co.nz/mailman/listinfo/delphi">http://ns3.123.co.nz/mailman/listinfo/delphi
</a><br><br>_______________________________________________<br>Delphi mailing list<br><a href="mailto:Delphi@ns3.123.co.nz">Delphi@ns3.123.co.nz</a><br><a href="http://ns3.123.co.nz/mailman/listinfo/delphi">http://ns3.123.co.nz/mailman/listinfo/delphi
</a><br></blockquote></div><br>