Posted by Thomas Mercer-Hursh on 14-Sep-2013 10:44

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.

All Replies

Posted by Bill Wood on 02-Jan-2014 12:59

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 :-) )

Posted by Thomas Mercer-Hursh on 02-Jan-2014 13:05

I can't see PSC going wiki for the whole thing ... there would be a real governance issue, among other things.

Posted by Peter Judge on 02-Jan-2014 14:21

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.

Posted by Thomas Mercer-Hursh on 02-Jan-2014 15:11

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.

Posted by Tim Kuehn on 02-Jan-2014 16:50

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.

Posted by Thomas Mercer-Hursh on 02-Jan-2014 17:02

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.

Posted by Tim Kuehn on 02-Jan-2014 17:09

[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. 

Posted by Thomas Mercer-Hursh on 02-Jan-2014 20:11

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.

This thread is closed