[Moderator] List guidelines and related resources (updated)
[Moderator] List guidelines and related resources (updated)
- Subject: [Moderator] List guidelines and related resources (updated)
- From: mmalcolm crawford <email@hidden>
- Date: Mon, 1 May 2006 00:40:57 -0700
[Update:
Added to "on-topic" section.
Expanded section on use of documentation.
Added note about Option/Command double-click in Xcode.
Added description of different types of documentation (thanks to SA).
]
****
Please Stay On-Topic
====================
Bear in mind that there are several thousand subscribers to the Cocoa-
dev list, including many Apple engineers. Every post in effect costs
the Cocoa community hundreds of dollars to process (and takes time
away from the engineers who might be working on the fix to your bug!).
In 2005, over 26,000 messages were sent to the list. In order to
keep the list useful and to maximise your chances of getting an
answer to your question, please stay on topic and adhere to the
guidelines given in:
"How To Ask Questions The Smart Way"
<http://www.catb.org/~esr/faqs/smart-questions.html>
If someone posts a message that is off-topic, please do not reply to
the list. You should contact the sender directly or alert a
moderator. If a moderator flags a thread as closed (typically with
"EOT" in the subject line), do not continue to post to that thread.
****
Cocoa-related resources
=======================
Cocoa-related resources that may answer your question without the
need to wait for a reply from the list:
Apple's documentation
---------------------
The Cocoa Getting Started page.
If you haven't read any Cocoa documentation and want to
learn about
the technology, you should begin with this.
<http://developer.apple.com/referencelibrary/GettingStarted/
GS_Cocoa/>
<http://developer.apple.com/documentation/>
<http://developer.apple.com/documentation/Cocoa/Cocoa.html>
Apple produces several kinds of documentation:
- Reference
This is intended to be the canonical reference for all the available
classes, methods and functions. It is intended to be a concise
description of the APIs. It typically does not include example code
or additional conceptual material. To find relevant conceptual
material, you should look at the "Companion Document" listed at the
top of the reference.
- Conceptual and Task Books
Conceptual books (including tutorials) are typically intended to be
read through from start to finish, and cover the basic concepts of a
technology, along with additional advanced concepts. These books
often contain sample code.
The task books cover more specific topics that are not necessarily of
interest to all developers. They're more detailed and more specific
to a sub-area of the overall conceptual area that they cover. These
books should have significant sample code where appropriate.
Not all the current documentation has the conceptual and task
material separated into distinct books, often they co-mingle.
* Finding documentation
If you are not sure where to find documentation relevant to your
problem, a useful strategy is to go to the API reference for a
relevant class and look at its companion document. You can also
search the online documentation suite using the search field at the
top right of the page (see, for example, <http://developer.apple.com/
documentation/Cocoa/index.html>). It is often a good idea to check
the "Restrict to Cocoa" box. If you need more precise search, you
can use the Advanced Search panel at <http://developer.apple.com/
search/>.
Remember you can also view and search the documentation in Xcode --
see the "Help" menu. You can see all the methods associated with a
class (and links to relevant documentation) using Xcode's Class
Browser (see the Project > Class Browser menu item). In Xcode, you
can Option-double-click on a symbol to look it up in the
documentation, and you can Command-double-click on a symbol to go to
the header file in which it is declared.
* Keeping documentation up-to-date
You can keep your local documentation up-to-date by using the
Documentation update preference in Xcode. Apple's developer
documentation is updated en bloc about once a month. An update
package is made available at about the same time that updates are
published on the web site.
Code examples
-------------
Apple provides code samples in two places, on-disk (installed with
the developer tools) and online:
Developer examples
<file:///Developer/Examples/AppKit/>
ADC
<http://developer.apple.com/samplecode/>
Online resources
----------------
"UNOFFICIAL Cocoa-dev Frequently Asked Questions"
<http://www.alastairs-place.net/cocoa/faq.txt>
Especially useful for pointers to documents relating to
memory management
and book recommendations
List archives
<http://lists.apple.com/archives/cocoa-dev>
Combined Apple and Omni Cocoa developer list archives
<http://www.cocoabuilder.com/>
Cocoa-related sites
<http://www.cocoadev.com/>
<http://www.cocoadevcentral.com/>
<http://www.stepwise.com/>
Cocoa Bindings
<http://developer.apple.com/documentation/Cocoa/Conceptual/
CocoaBindings/>
<http://developer.apple.com/documentation/Cocoa/Reference/
CocoaBindingsRef/>
<http://developer.apple.com/cocoa/cocoabindings.html>
<http://homepage.mac.com/mmalc/CocoaExamples/controllers.html>
<http://www.cocoadevcentral.com/articles/000080.php>
<http://www.macdevcenter.com/pub/a/mac/2004/04/06/cocoa.html>
Google
<http://www.google.com/>
(It is sometimes the case that using the subject line of a post
as a search term in Google will yield an answer...)
Memory management
=================
Developers are strongly discouraged from attempting to reformulate
Cocoa's memory management rules in posts to the list. Almost
invariably, someone makes a subtle or not-so-subtle mistake which
then results in confusion and additional messages to resolve the
issue. Simply post links to the relevant documentation, such as:
<http://developer.apple.com/documentation/Cocoa/Conceptual/
MemoryMgmt/Tasks/MemoryManagementRules.html>
List etiquette
==============
In addition to the guidelines given in "How To Ask Questions The
Smart Way", please ensure that you abide by the list rules:
<http://lists.apple.com/tc.html>
<http://lists.apple.com/tips.html>
In particular: please "Edit included messages in replies to
minimize the amount of text." There is no need, for example,
to include the list footer in your reply.
Note that you should never post to the list any message that was
sent to you
privately unless you have the original author's permission.
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Cocoa-dev mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden