how to disturb newbies

[Jeff Reynolds]

One thing also with documentation like the, and newbies are the most vulnerable to this, is how well written it is and does it cover all the steps (ie not start c, d, e...). It hard for a high end development crew to hopefully have the ability to write and edit to a very clean and readable style and also not take some of the very basic knowledge for granted. To really do this well you either have to be extremely luck and have someone on staff that just happens to have writing and/or editing (but both should not be done by the same person if you want great results) as second talents/skills or hire in professional help. 

In all the companies, organizations and projects I've worked on in the last 35 years or so, in just about every case the writing and editing of any documentation, grants, and, at times, even content to be presented was given some of the lowest priorities and usually there were enough staff that were considered (or self appointed) good enough writers to the task, but usually proved pretty sadly wrong whenever there was some professional work done to compare it to (most especially true in copy editing, even those considered really good are not compared to the truly good ones, I know I've worked with them on projects up to a million words).

I'm not saying at all the rev dictionary is poorly written at all. I have always found it very good for me for the most part (more info would always be great and a notes function useful as well), but I'm dyslexic and thus when I read I tend to suck out meaning and toss language out (you should hear me read out loud) and thus the opposite of the average user (language plays a more front and center role in non dyslexic readers and why it can muck up content/meaning for them easily.) Even though really good writing and editing is partially lost on me, I really understand its impact on the end user as I've been doing content design, development and production a long long time and have seen the proven results.

Just saying if you really want the more average user and newbie to really grock the material that nuance of a professional giving all the content a good pass really can help and it tends to be the last priority unfortunately.

Cheers

Jeff

> On Oct 26, 2014, at 7:00 AM, use-livecode-request at lists.runrev.com wrote:
> 
> I fully agree. The dictionary is very important to shape the first impression of newcomers about LC. I have read and heard several disparaging comments about the documentation which are a very negative publicity for this fantastic product. I perfectly understand that it is far more interesting and stimulating for the small staff in Edinburgh to develop new features - and they are brilliant at that - than devote time and energy to do the house cleaning on the documentation. But it's a vital part of how their work is appreciated outside. I would suggest Kevin to establish a weekly "hour of dictionary cleaning" for everybody. Most of the dictionary problems could be solved in such a short time.