I wonder if there might be a value in creating a forum for documentation issues. There are periodic remarks here and on PEG about example code in the documentation which is dubious in terms of good programming practice. As far as I know, none of these comments ever lead to changes in the actual documentation. In a way, this is understandable since I am sure that the documentation folks are scrambling to create documentation for new features .. whose specificiations keep changing ... and probably the source of the code examples puts more stress on showing a specific construct in as few lines as possible, rather than providing a model for good ABL programming. But, I would think there was an opportunity for one person or a part of one person to both periodically revise old examples that had been identified as showing bad practice. And, possibly this could be coupled by developing a program to review new examples by a customer panel selected to represent good practice. Once that sort of thing got working, one could even tackle projects like reviewing a particular chapter.
What specifically made me think of this is the example on page 224 of the OOABL manual which shows newing a helper class in a constructor. To me, one should never do anything in a constructor that can possibly fail because one is left with an object that one thinks exists, but doesn't. Much preferred, I believe, is to do any such work in a separate Initialize method, where handling the errors and the object existence is much clearer.
Of course, the problem may be that there would not be a consensus on what was good programming practice ...
But, it would also be a potentially interesting byproduct of such an effort to have a web site where one published each new discussion about what was good practice, including any dissenting opinions and reasons.
I always thought a "wikipedia"-style documentation site would be useful/interesting. Experts (or otherwise) in the Community could 'extend' (fix?) the documentation.
There is definitely the 'best practices' angle that you mention, but also you could add clarifications or examples (I particularly dislike documentation that is technically correct but not that useful because you can't tell what to do with the information :-) )
I can't see PSC going wiki for the whole thing ... there would be a real governance issue, among other things.
The discussion thread on good practise is relatively easy now that the doc is provided in a linkable way. For instance, you could start a discussion from your above example via the documentation link .
I also think that wikipedia style doc would be good for reference-type doc. Wikis usually have good governance built in to the platform.
I still think there are two fairly separate issues here. One is about access to the documentation itself and, for me, the PDF is just fine for that. The other is feedback ... lots of people make comments, but few have any impact because they are made on forums where no doc person is listening for feedback. Yes, directly annotating the point in the text is one possibility, but one which can lead to all sorts of arguments and confusion ... and I don't expect PSC to adopt a really open approach to doc any time soon. The real point is to have a place to lodge comments where they are visible both to the people responsible for the doc and to the public in case there are others who want to second or counter comment.
I've been collaborating with PSC on the doc issue, and when I see things that are interesting on the forum and elsewhere I'll forward it to my PSC contact.
One possible advantage for the wiki-style would be code samples. The current ones don't do well, so having some "real life" demo sample code would do everyone good.
Nice offer, Tim, but there really should be a direct pipeline from all of us to the doc folks. Among other things, we may have different ideas.
[quote user="Thomas Mercer-Hursh"]Nice offer, Tim, but there really should be a direct pipeline from all of us to the doc folks. Among other things, we may have different ideas. [/quote]
1) I didn't make an offer.
2) If you want a 'direct pipeline', then find the decision makers, talk to them, and make sure your interaction is a good use of their time.
You said "when I see things that are interesting on the forum and elsewhere I'll forward it to my PSC contact." To me, that sounds like an offer to make sure that things ... at least those which you find interesting ... get to the right people.
My point in this thread is that it should not depend on each individual establishing a relationship and proving their worth. There should be an obvious channel by which anyone can provide feedback and expect that the relevant people will notice. This, I believe, is one of the things which Jean has in mind for the new forum.
In fact, this thread should perhaps be moved to the Community Forum.