[Moderator] List guidelines and related resources

FROM : cocoa-dev-admins
DATE : Fri Jul 07 19:08:43 2006

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.

If you post a message that is blatantly off-topic, you are liable to 
be suspended.

****


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.

[+] If you post a message to the list and do not get a reply, you 
should not simply repost the message.
    There may be reasons why no-one has answered -- see <http://www.catb.org/~esr/faqs/smart-questions.html
>.
    If you want to send again, add more information or background, or 
explain what further steps
    you have taken in the interim to solve your problem.

The following was written to address the reasons the Ruby on Rails 
community isn't what it once was, but it could easily be true of any 
number of communities.  Please help to make sure that the cocoa-dev 
list doesn't head in the same direction:

    <http://www.slash7.com/pages/vampires>




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/
>

Main documentation links:
    <http://developer.apple.com/documentation/>
    <http://developer.apple.com/documentation/Cocoa/Cocoa.html>


Apple produces several kinds of documentation.  For an overview of how 
to use the documentation, see:

    <http://developer.apple.com/referencelibrary/usingreflib.html>
and
    <http://developer.apple.com/macosx/newinreflibrary.html>

* 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.  If this is the case, you have 
probably not invested sufficient
    effort into finding an answer to your problem, and you are likely 
to receive a reprimand.)


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
>
Links to other reviewed articles that discuss memory management are 
given in <http://www.alastairs-place.net/cocoa/faq.txt>