Re: A documetation suggestion (was Re: Cocoa et al as HCI usability problem)
Re: A documetation suggestion (was Re: Cocoa et al as HCI usability problem)
- Subject: Re: A documetation suggestion (was Re: Cocoa et al as HCI usability problem)
- From: Jonathan Hendry <email@hidden>
- Date: Thu, 22 May 2008 11:15:14 -0400
Perhaps a better way of doing this would be a web or WebKit app with
two panes. One that shows the Apple docs at Apple's site, and the
other pane points to a page at a non-Apple wiki site that corresponds
to the currently displayed Apple site.
That would ensure that the Apple content stays up to date, while
allowing unlimited wiki commenting.
- Jon
On May 22, 2008, at 10:39 AM, Julius Guzy wrote:
On 22 May 2008, at 4:55, David Casseres wrote:
That's a really good idea, your wiki-that's-more-than-a-wiki.
You're in charge!
8^{)
Ha Ha
But just as a matter of interest, how would one set about talking
to apple about such a thing?
I would guess one would need first to demonstrate some kind of a
consensus
and then thrash out a suitable format and mechanism within the group?
Julius
On May 19, 2008, at 5:31 AM, Julius Guzy wrote:
Well I never thought I would cause this much discussion.
I have tried but do not have the time needed to reply to all.
I might still but work must take precedence.
There have been a number of people who suggested I give specific
instances of documentation failure.
I agree it would be useful but I am not going to.
The process would require far more analysis than I can afford at
present.
Let me see however if I can summarise some of the discussion and
finish with a suggestion.
The current documentation works for some people and not for others.
Those who find it adequate tend to be those who know how to
program the machine.
Those who find it less than adequate are those learning how to
program the machine.
Most of those learning how to use the machine already have
considerable experience in programming in a wide variety of
languages and on a wide range of platforms.
Most of those learning to use the machine have put quite a bit of
time and effort into doing so.
This list contains a lot of people happy to share their expertiese.
There is a need to identify particular difficulties with the
documentation etc.
Ok to cut to the chase.
There exists a very large body of documentation belonging to
Apple and which ultimately we all need to be acquainted with if
we are to get the most out of the machine.
This documentation is a resource that could be built on.
I wonder if Apple would be prepared to provide a copy of its
documentation that could be turned into some kind of a wiki?
There already exists a cocoa wiki but it suffers from the fact
that the scope of the problem is far too large even for a
dedicated band of people to tackle in their spare time without
this additional resource.
Starting with a ready made body of information would have a
greater chance of success.
When I say "some kind of wiki" I do not actually mean a wiki.
That it seems to me, would be a huge undertaking.
What I have in mind is more of an FAQ approach.
For instance take a page documenting something like NSString or
NSArray .
Then for each of the sub-headings/sections whatever there would
be provided a means for entering questions and providing answers
to those questions.
Tthe entry of a question would cause an email to be sent to a
list which specialises in programming problems or to a list
created specifically for this pupose and similarily for the answers.
When people see the email they can if they wish go to the
documentation and provide an answer.
When people see an answer they can comment upon it, extend it etc.
I would keep it all very simple and very basic so it stays
managable.
If useful it would acquire its own dynamic.
I think the advantages of such an approach might be considerable.
1. We discover exactly where the difficulties lie.
2. We provide ready answers to those difficulties.
3. People are encouraged to explore the documentation
4. The documentation becomes up to date, errors are corrected etc.
5. There is little extra effort expended in providing the answers
than would be spent doing so on this list
6. The context of the question and the reply is that much more clear
7. There is a build up of information concerning a specific
problem all in the same place.
8. It builds a self help community.
9. It could result in a pretty good piece of documentation.
It is just a thought
must rush
Julius
http://juliuspaintings.co.uk
_______________________________________________
Cocoa-dev mailing list (email@hidden)
Please do not post admin requests or moderator comments to the list.
Contact the moderators at cocoa-dev-admins(at)lists.apple.com
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden
_______________________________________________
Cocoa-dev mailing list (email@hidden)
Please do not post admin requests or moderator comments to the list.
Contact the moderators at cocoa-dev-admins(at)lists.apple.com
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden
Jonathan Hendry
Howard Hughes Medical Institute
Maunsell Lab
Harvard Medical School
_______________________________________________
Cocoa-dev mailing list (email@hidden)
Please do not post admin requests or moderator comments to the list.
Contact the moderators at cocoa-dev-admins(at)lists.apple.com
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden