PxPlus User Forum

Twitter Twitter Twitter

Author Topic: modernize the documentation  (Read 1172 times)

Thomas Bock

  • Diamond Member
  • *****
  • Posts: 131
    • View Profile
modernize the documentation
« on: August 09, 2018, 02:37:23 AM »
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

  • Diamond Member
  • *****
  • Posts: 131
    • View Profile
Re: modernize the documentation
« Reply #1 on: August 17, 2018, 05:56:28 AM »
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

  • Staff
  • Diamond Member
  • *****
  • Posts: 277
  • Don’t Panic
    • View Profile
    • PVX Plus Technologies
Re: modernize the documentation
« Reply #2 on: August 17, 2018, 09:01:20 AM »
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.
Software Developer for PVX Plus Technologies LTD.

Mike King

  • Administrator
  • Diamond Member
  • *****
  • Posts: 3416
  • Mike King
    • View Profile
    • PVX Plus Technologies
Re: modernize the documentation
« Reply #3 on: August 17, 2018, 09:27:35 AM »
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.

bokum32301

  • Member
  • **
  • Posts: 8
    • View Profile
Re: modernize the documentation
« Reply #4 on: August 19, 2018, 07:42:53 PM »
I still have and used the original spiral bound docs from pvx 4