Re: Another question re documentation style
- Posted by irv Sep 08, 2019
- 887 views
The source programmers may have the best insight, but they don't always explain things in an understandable way. Nor do they always produce test cases in which the results correspond to the documentation or vice/versa.
It should be obvious that if I document my function print_a() as "This will print A on the terminal", and go thru all the trouble to compile a new Eu version for several platforms, and next week someone reports that they tried my print_a() function, but it printed B instead of A, I have several choices:
- correct the function to match the docs
- recompile for all the platforms (with a new version, so people will know the bug has been fixed)
- re-create all new documentation from the source.
- prepare new release package(s)
Which, as we all know, isn't going to happen!
- just ignore it. In the next release (5 or 10 years from now) will be fixed (maybe).
Or, do the right thing:
- Update the on-line documentation to say "don't use function print_a() unless you want a B!"
Which is easier? Which will actually work? Which will take 10 minutes of your time. Which will take years?
