An Active Suggestion for Improving the Documentation of Scriptcase

[Orion]

Although I have been using ScriptCase for some time and consider it a great development tool, I still find myself bewildered and irritated by the documentation every now and then. For one thing, the English language used is often not correct, but even worse is the lack of proper explanation that can be understood by users new to SC or a specific area in SC. However, I do think that SC actually wants their product to be user friendly and well documented. They do put in a lot of effort on making videos, updating the documentation as well as the user interface, e.g. in the latest version there is a nice improvement in regards to macros so it is easy to see in which code sections each macro is available, and one can insert code snippets containing an example of usage of the macro.

Thus, rather than just criticise SC’s effort, I instead considered how we could actively assist in improving the written documentation which is available at http://www.scriptcase.net/docs/en_us/v81/manual_mp.htm.

This documentation tree consist of articles which over time could be improved, if those willing would chip in a bit here and there. The effort needed would not be much greater than answering a forum post every now and then, and I do believe that eventually it will actually reduce the amount of questions in the forum – especially those concerning basic usage of SC, reserving the forum to bugs and more complicated use cases.

Practically, the improvement could be implemented in this way:

1. A new forum group “Documentation” is created.

2. Every now and then an article from the documentation is selected by those willing to participate in the project. We could take turns.

3. A new draft for the article is submitted as a forum post. I could e.g. submit the article “sc_error_exit(URL, “Target”) or (My_Application, “Target”)”, which I find inadequate. The English language is given a touch up. The elements used could be properly explained, e.g. “Target” is not explained at all and there is a reference to “_blank” as a target which isn’t clarified. Of course you can do try and error, seach the forum, etc., but it is a waste of time when the basic documentation should just be adequate.

4. If any part of the documentation is not clear, questions is put as reply posts.

5. Other members replies with answers, notes and examples.

6. All forum posts and replies should have the same heading of the original article/section, giving general and detailed area, e.g. “sc_error_exit”, “Grid Modules”, “Form Settings”. This in and of itself will improve the forum, since users can search these subject and find the discussion of that feature of SC.

7. When everything in regards to the article/section has been cleared up and all relevant notes and examples given, a new draft is made, etc.

8. When the article is ready, the heading is changed to “[SOLVED]” by one of the super moderators (they can of course also participate earlier in the process) and the the revised article is updated in the website manual.

We will need the cooperation of SC’s super moderators and those in charge of the website manual at SC, but I do not see why they would not wish to assist in this effort. After all, it will only improve their development tool, lifting the documentation to a more professional level closer to the tool itself.

Again, I do not see this as a gigantic effort, but rather as long series of small efforts at the same level as answering forum post, but any contribution will have a more lasting result. Over time we will get a much improved documentation.

Let me know if you think this is a good idea and would be willing to participate in the effort.

[yourguide]

I would join in to help on this, I have a background in PHP development but have only been using ScriptCase for about a year. I find it’s documentation lacking good english descriptions of what things do also. I would help in any way that I could.

[Cavadinha]

It seems to be a very noble idea, on paper.

Users notes would be awesome on the areas that require coding, no doubts about that.
For example: events, custom php function that is used to improve the app, javascript codes that makes new things, proper example to the use of macros, etc.

You can see something like this when you browse functions at php.net

Putting this aside, the only think that in my opinion will work properly is to making a community manual, where people could edit the articles and stuff.
Wikipedia’s style, where a moderator would approve the changes.

It could work, however I am not sure if we have the man power to assist you guys in this.
We probably would moderate yes, but the problem is to put an effort to start this.

[Orion]

Thanks, yourguide, for being willing to participate in this effort.

And thanks, Cavadinha, for offering your viewpoint.

To build a wiki or manual from scratch is not what I have in mind. Why do that, when you already have a Scriptcase online help system that can be used as a basis. My idea is to simply take the articles as they are and slowly, bit by bit, improve them – an elephant can be consumed, only one has to do it by regular, tiny portions.

In order to avoid a huge workload in building documentation from scratch, introducing new wikis besides the forum, etc., my idea is to just use the existing forum with a new section “Documentation”. In that forum section, only a single selected part of the existing documentation is handled at a time. For example, the article on the sc_error_exit macro is confusing, unless you already know several SC technical terms (e.g. “Target”) from other articles in the web help.

So, one just makes a new forum post with “sc_error_exit(URL, “Target”) or (My_Application, “Target”)” as the subject and the original text with an improvement of the English language, expansion of the text, explanation of special SC terms, etc. If the author of the revised article has questions about anything in it, he can post them as replies to original post, and more experienced SC developers can chip in with replies to these (even the SC super moderators). Also, notes can be made as replies and possibly included in the article itself. When all is clear, a final edition is made and given over to SC.

Now Scriptcases’ contribution come in to the picture. We hand you a new version of the article on a silver platter and you just have to update the existing web help with it. This should be doable. In fact, I think this would be a very good offer to you from the community (if it becomes a reality), because as a supplier of an international tool, you should have a dedicated English speaking technical resource to keep your documentation in an excellent state. You do not have this resource, so I see this as a next best option.

Now, of course it would perhaps be more ideal to build a new wiki like help system (e.g. something like the PHP help which I also like) into which the existing web help would be inserted, so that all changes could in the system itself, but I dont think that anyone would be willing to put in that much effort. Thus, I would rather use what we have and see some fast results. We could for example decide to do all the macro articles first, one at a time, so regular changes can be seen – if only you are willing to update your web help with the new, revised articles.