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
rich...@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.
_______________________________________________
use-livecode mailing list
use-livecode@lists.runrev.com
Please visit this url to subscribe, unsubscribe and manage your subscription
preferences:
http://lists.runrev.com/mailman/listinfo/use-livecode
