A documetation suggestion (was Re: Cocoa et al as HCI usability problem)
A documetation suggestion (was Re: Cocoa et al as HCI usability problem)
- Subject: A documetation suggestion (was Re: Cocoa et al as HCI usability problem)
- From: Julius Guzy <email@hidden>
- Date: Mon, 19 May 2008 13:31:30 +0100
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