Hi Jeff,
While I appreciate Don's vote of confidence, I'm as aware as anyone that the docs could be improved. At the end of the day I have a finite amount of time, and finding the balance between fixing bugs, implementing new features, and doing documentation is difficult. It's somewhat natural that the emphasis tends to oscillate between features and docs on a regular basis.
Even when the docs are a priority, working on the "right kind" of docs is also an art. Documentation can be of a tutorial nature (like the 2010 book) or a more referential nature like the existing shipping docs. And even there should the focus be on documenting the template, the classes or the underlying concepts?
To be honest, we probably disagree on the priorities, at least as far as documenting the classes themselves go. That's not to say that tha is unimportant, just that it renders little value without a contex to plug it into. Plus it is the simplest to absorb without docs - in the sense that all the methods are listed in net web.inc and all the code can be read in netweb.clw. But reading the methods out of context helps you very little (which is why just studying the code is less helpful.)
Over the past 5 years or so we've tried to make training available to shorten the learning curve, and that is an ongoing effort. Training, and training materials are usually outside the scope of the actual product, so we have to try and keep these efforts economically viable, which means more cost to end users. That's something I try and avoid, but we all live I the real world.
Current documentation efforts are being concentrated in two areas. The first is to update the book to make sure that it remains correct, and is expanded to cover event more information at a conceptual and tutorial type level. This will remain the primary tool for "learning" - especially for beginners.
The second focus is on updating the template refereence. This is the most important key to covering what the tool is designed to do easily for you. A new template reference has already been started, but it is a fairly large task and will take some weeks to complete.
Existing ancillary documentation also needs to be checked for accuracy, and that has been happening since NT6 shipped, and is an ongoing effort.
Of course it really doesn't matter how much documentation there is - if you're trying to do something for the first time it can be a challenge, regardless of how simple it is. If there isn't a bit somewhere saying "this is how you do x" then the docs aren't helping. This is made worse by the fact that most NT users are already very proficient in Clarion, and are not used to simple tasks taking a long time.
NetTalkCentral has a key role to play in this regard, because chances are other programmers have walked the road before you, and may either be able to help directly, or give you clues to getting going.
Frankly I'd love to take a month off from bug-fixing and just write docs, but I'm acutely aware that I could do that and still not benefit the community at large. That approach doesn't really help folk, like yourself, who have programs to write, and deadlines to make.
In closing, yes, it's a balance, but the docs are not forgotten. They are an important piece of the puzzle, and they do get time and effort spent on them. Alas though I cannot describe every possible task, or document every possible bit of embed code. So I do recommend asking on the forums when you do have issues. Some questions are harder to answer then others, and some highlight areas that need to be improved, but continued dialog is necessary for all concerned.
Cheers
Bruce
Topic: The State of NetTalk Documentation (Read 2692 times)