1. Another question re documentation style

I notice that few (or none) of the doc examples given with the various functions bother to include the library being used:

Example for std/console.e:

clear_screen()  
display_text_image({1,1}, {{'A', WHITE, 'B', GREEN},  
                           {'C', RED+16*WHITE},  
                           {'D', BLUE}}) 

If a new user tries this simple code, he gets:

<0074>:: Errors resolving the following references:
    'WHITE' (my_test.exc:2) has not been declared. 
    'GREEN' (my_test.exc:2) has not been declared. 
    'RED' (my_test.exc:3) has not been declared. 
    'WHITE' (my_test.exc:3) has not been declared. 
    'BLUE' (my_test.exc:4) has not been declared. 
    'display_text_image' (my_test.exc:4) has not been declared. 
 
                           {'D', BLUE}}) 

You'll note that nowhere in that error message is it mentioned that his program needed to "include std/console.e".

So, should the demonstration programs have the needed includes added?

include std/console.e -- like this? 
clear_screen()  
display_text_image({1,1}, {{'A', WHITE, 'B', GREEN},  
                           {'C', RED+16*WHITE},  
                           {'D', BLUE}}) 
new topic     » topic index » view message » categorize

2. Re: Another question re documentation style

irv said...

So, should the demonstration programs have the needed includes added?

Yes, I would think the examples should be functionally correct as shown. Some examples might even need to use different libraries, so having the correct include statements would be helpful.

-Greg

new topic     » goto parent     » topic index » view message » categorize

3. Re: Another question re documentation style

So far, much if not most of the demo code attached to the docs is faulty.

For example, datetime:now()

 
dt = now() 
-- dt is the date and time 
 

See anything wrong? How about the fact that dt hasn't been declared? Also, the fact that std/datetime.e has to be included has been forgotten. And lastly, where is the result? What should it look like? How do I see it?

A newcomer is going to fail at least 3 times to get any usable output from this one-line program!

Let's do it right:

include std/datetime.e 
 
object dt = now()  
? dt -- display the results 

Output:

{2019,9,7,17,30,38}

It's been wrong for a very long time. And that, friends, is why locking the documentation into source code where it can't be changed is a bad idea.

new topic     » goto parent     » topic index » view message » categorize

4. Re: Another question re documentation style

You might could make this one minor change for technical correctness*:

irv said...

Let's do it right:

include std/datetime.e 
 
-- object dt = now()  
datetime dt = now() 
 
? dt -- display the results 

Output:

{2019,9,7,17,30,38}

And that, friends, is why locking the documentation into source code where it can't be changed is a bad idea.

We need some way to keep docs in the source, just for the fact that the source programmers have the best insight; maybe we could just output an outline so that the documentation managers can make sure they cover every base. We could also make a provision, at least for the online docs, to have comments. These could then be incorporated into the docs and marked appropriately (maybe allow ticket creation straight from the docs pages?).

* which, I've heard, is the best kind of correctness. grin

ADDED: It would be cool, also, to show more advanced (or useful) output with format() to get a human-readable date, and even a translation to another language!

new topic     » goto parent     » topic index » view message » categorize

5. Re: Another question re documentation style

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?

new topic     » goto parent     » topic index » view message » categorize

6. Re: Another question re documentation style

I think anything we can do to streamline future releases is a worthwhile effort. But you're asking to completely replace a documentation process that's already set up, and that's a huge task.

What you're asking for requires an entirely new approach to how we store and edit documentation, and it reverses the relationship we currently have between code and documentation.

And if this is the route we're going, shouldn't we plan out an approach rather than changing things ad hoc as we go? What's our plan here? How do we future-proof this approach?

What I'm looking for right now is to just proofread what we've got so we can get it packaged into a release. Once we get a release out, then we can revisit things that need improving.

Please also keep in mind that I'm working on a new website to make these types of changes to our operation easier by reducing the code required to add new features to the website.

-Greg

new topic     » goto parent     » topic index » view message » categorize

7. Re: Another question re documentation style

irv said...

Which is easier? Which will actually work? Which will take 10 minutes of your time. Which will take years?

The easiest is to have rolling releases every 3-6 months. smile

new topic     » goto parent     » topic index » view message » categorize

Search



Quick Links

User menu

Not signed in.

Misc Menu