Help File Improvements

Anobium
2014-07-06
2014-07-08
  • Anobium
    Anobium
    2014-07-06

    See https://sourceforge.net/p/gcbasic/discussion/629990/thread/fede45cc/?limit=25#6dd7 for the start of this thread.

    This point of discussion is the quality of the Help file - 'to have multiple eyes proofread all the Help files for consistency, accuracy and eye-appeal to beginners. The quality see it, that's the main stumbling block right now. There is no doubt in my mind that Great Cow Basic is the premier compiler for microcontrollers, but until we document it properly no one will ever know and it will languish.'

    I cannot agree more, I like the idea of the proof reading for consistency, accuracy and eye-appeal to beginners. In the last year the Help file has expanded to cover most of the capabilities of Great Cow Basic - we have a baseline.

    All help to edit and revise the Help file would be gladly accepted. What is the best process to get the reviews and improvements completed? And, who is willing to assist?

    Your help will improve Great Cow Basic.

     
  • Thomas Henry
    Thomas Henry
    2014-07-07

    A couple ideas:

    1. Make the entire Help file available as one complete document, in ordinary Word or Open Office Writer format. The notion is that the document would undergo proofing by everyone involved as though it were a print document--a manual, as it were. This will help with the consistency aspect. Everyone will see it as an organic whole, and perhaps catch on to the style.

    2. Everyone who pitches in chooses two or three of the topics to work on individually.

    3. Obviously, with a variety of people writing/rewriting these topics, there must be an editor-in-chief whose duty it is to proof the final document for formatting consistency.

    4. Only after a final approval by all, and especially Hugh, would it finally be converted back into the Window Help format.

    A few suggestions:

    1. The example programs should be as simple as possible, focusing exclusively on the command in question. Let's strip away all inconsequentials so the beginner sees exactly what the command is up to and not be confused by unrelated issues. By keeping it simple and to this point, this should also encourage him or her to try it out on the breadboard.

    2. Avoid vacuous chatter. I hate it when I see something like: "The PrintLCD command is used to print to the LCD." In other words, comments should explain, not parrot. This is especially true for the more obscure or difficult commands. For example, I'm still struggling with I2C, yet I'd be willing to bet that all would become clear with one or two well crafted sentences. A related problem is when the Help topic mimics the source code.

    3. Ensure that all user-set constants required by the include files are described.

    Well, those are a few of the things I've pondered. And to answer Anobium's question, yes, I will volunteer to help. Who else will sign up?

    Thomas Henry

     
  • I have taken the .chm file and run it through a chm to doc converter.
    It does help to have it in one document.

    I send Evan corrections when I find them.
    I've found on a project like this you are never done correcting and updating.
    But overall, the help file has improved 1000% over where it was just 2 years ago.

    Personally I feel we need more examples posted which seemed to be the most beneficial for Arduino. There really isn't a great Arduino help file but there is lots of sample code.

    That's what I'd like to see organized/expanded.