wait with messages

Richard Gaskin ambassador at fourthworld.com
Tue May 6 09:45:11 EDT 2014


Kay, thanks for that post - you raise some important points.

Even better, yours is perhaps the first discussion of the User Guide 
I've seen that describes specific actionable items.

The core team at RunRev has been working on a rewrite of the User Guide 
for a future version, where the scope of changes in the engine will very 
much require it.

But in the meantime there's been much discussion in my meetings with 
them about the possibility of an interim update, which will be needed at 
least through the remainder of the v6.x series and possibly into v7.

I recently created a new section in the Forums for "Documentation" - 
it's not yet active (Heather and I are sorting out a PHPBB issue), but 
the goal there is to see if our community is at the place yet that all 
good open source projects eventually arrive, where we're big enough to 
have a Documentation Team among community members.

The folks at RunRev have been anticipating that, and have included Docs 
in their outline for community contributors:
<http://livecode.com/community/contribute-to-livecode/#%20Writing%20Documentation>

To get started we'd need only about three to five people, with one of 
them willing to be the team leader.

If anyone here is interested in participating please drop me a note and 
we'll get that discussion going just as soon as Heather and I can put 
the new Documentation forum online.

--
  Richard Gaskin
  LiveCode Community Manager
  richard at livecode.org


Kay C Lan wrote:

> On Fri, May 2, 2014 at 7:32 AM, Richard Gaskin wrote:
>
>> I would imagine that after that much time there would be an error or two
>> in it, but I haven't come across specific inaccuracies, and I've been
>> asking for months and haven't been able to find anyone else who can help me
>> turn up any.
>>
>> As a User Guide it remains a good starting point to get the lay of the
>> land, with the updated-with-each-release Dictionary for token details.
>
> Maybe it's not an inaccuracy as such, but I think there is a gotcha for Mac
> users new to LC when referring to the Dictionary and the User Guide. The
> User Guide typically uses the terms Mac OS and Mac OS X as interchangeable
> (Page 11 - 7.13.6 Menu Bars on Mac OS Systems [no mention of Mac OS X
> menubars]. As the latest LC doesn't build for OS 9, and a new user to LC
> isn't ever likely to think about building for OS 9, this is completely
> acceptable and understandable. But, the Dictionary does distinguish between
> Mac OS and Mac OS X because many of the references do date back to OS 9
> compatibility. See the entry for specialFolderPath(). The problem arises
> when an entry or example ONLY has a reference to Mac OS - see 'address' in
> the Dictionary.
>
> Any new user to LC who reads the User Guide and reads Mac OS will think OS
> X, and that is basically correct. But when they go to the Dictionary and
> see examples that are only Mac OS, they'll think they'll work on OS X and
> there is a good chance they'd be very frustrated because they do exactly
> what the example says but the do NOT get the result the Dictionary say they
> should get.
>
> Every example in the Dictionary for Mac OS [Classic] needs to be removed
> and replaced with an OS X example if it doesn't exist, or if it does, a
> much more useful iOS example, if applicable.
>
> There are the odd entries in the User Guide where the differentiation
> between Mac OS and Mac OS X is made (11.3.2 OS X file Types. 11.3.3 Mac OS
> Classic File Types), I'm not sure 11.3.3 is of much use to anyone today.
>
> I think the last version of Revolution to run on Mac OS was 2.6.1 so the
> User Guide and Dictionary need to be standardised so that ONLY the term OS
> X is used, or if the TM & Logo Police so dictate, Mac OS X. All references
> to Mac OS should be removed as there is no longer a need for Classic
> information.




More information about the use-livecode mailing list