modernize the documentation

Started by Thomas Bock, August 09, 2018, 02:37:23 AM

Previous topic - Next topic

Thomas Bock

We consider line numbers to be definitely outdated. That's why we configured the environment to throw error 85. That works great. But each new trainee stucks when he/she copies the samples from the documentation in order to learn the language. The young people have grown up with programming languages, which don't use line numbers. Explainig this concept requires the words in the past not later than in the 3rd sentence. As we're working today on programs that will run tomorrow, it seems neccessary to me to mention the old style in the documentation but to modernize the samples.
So, can you please remove the line number references in the samples?
... and please don't use "goto" any more as well.

Thomas Bock

Sorry, but I must post a followup.
Our trainee blunts her teeth with the samples for POS. Taking a look at the sample code I don't believe my eyes. All 10 samples throw error 20. That is not what a documentation is mode for. I fear there are more of these.

We - the senior developer - don't need a correct syntax in order to learn how a new feature works. But the next generation believe what they read.
Well, there is a real call for action.

Devon Austen

Hi Thomas,

The examples in the POS() function documentation all look correct. An example in the documentation does not necessarily mean a code/program example. In the case of the POS() function and probably a lot of the other functions the example is just of use of the function. It shows you a specific call to the function and the example tells you what the result is. Obviously if you want to use the function in a code/program you need to do something with the output or you will get a error 20.

Making every example in the documentation actual code/program examples would possibly make the examples less concise.

By necessity the documentation must assume a basic understanding of PxPlus syntax. The basics are documented but all that info can't be on every page of the documentation. Beginners need to learn some of the basics like, that it is a syntax error to call a function and do nothing with the return value, and how line numbers work. If they do that they they should have no problem with the documentation.
Principal Software Engineer for PVX Plus Technologies LTD.

Mike King

As a follow up Devons comment, the examples in the POS function are prefixed by a statement:

Given A$="The quick brown fox":

Based on this being the case and A$ has the specified value, the examples of the function formats and what they will return are all correct.
Your trainee likely missed the fact that A$ had to have a value which is why they misunderstood the examples.

As for the the examples not being complete/functional statements, the assumption is that the reader has a basic understanding of what a function is and how should be used.

Lastly, your earlier comment about GOTO is inappropriate given that most PxPlus applications have come from older programs where GOTO was generally used extensively.  Given that often documentation is used by trainee programmers (as you mentioned), these individuals need to understand the use of the GOTO directive if they hope to maintain older applications.  Not providing examples using GOTO would leave these trainees at a disadvantage, much as not including text mode directives such as INPUT or ACCEPT given newer application are primarily graphical.  The that point, even not showing the use of line numbers, would also be problem for new hires attempting to learn the environment.

Not every PxPlus application is fully graphical using structured programming techniques without line numbers or GOTOs.
Mike King
President - BBSysco Consulting
eMail: mike.king@bbsysco.com

bokum32301

I still have and used the original spiral bound docs from pvx 4