Technotes
AUTHOR'S
GUIDELINES
By Tom Maremaa, Technote Editor
TM@applelink.apple.com
Apple Developer Technical Support (DTS)
This is a preliminary Author's Guide to the new structure that Apple has evolved for Macintosh Technical Notes.
CONTENTS
A New Set of Changes
If you've read Macintosh Technical Notes in the past, you'll notice from the Technotes on Apple's Web site and on the Developer Reference Library
Edition CD that a number of important changes have occurred from the "old" Technotes. Some of these changes include
- a new name -- Technotes (one word) rather than New Macintosh Technical Notes (some of the "New" Notes were ancient, straining the definition of the word "new")
- a new structure and organization for the Technotes (which is explained in detail later in this document)
- a new numbering scheme that starts with Technote 1001 and moves upward sequentially from there with no numbering gaps, "missing" or "lost" Notes
- an emphasis on providing developers with the latest, most important information on new and emerging Apple technologies, such as PCI, QuickTime, QuickTime VR, and QuickDraw 3D, as well as updates to existing technologies and issues involving the Mac OS, present and future
- extensive peer review of Technotes to improve the quality and technical accuracy of each Note
- a new publication strategy, emphasizing timeliness and currency, with first publication on Apple's Web site at <http://www.info.apple.com/dev/technotes/Main.html>, where the Technotes are searchable by title, number, author, category and content, followed by publication on the Developer CD series and elsewhere
Historical Perspective
Macintosh Technical Notes have had a rich and colorful history at Apple. Many have been the product of inspired writing efforts and long hours of midnight programming. Some notes go all the way back to 1984 and even earlier. And more than 350 notes have been produced by Apple engineers, working in Developer Technical Support and other divisions of the company, since the mid-1980s.
The tradition at Apple of engineers, both in and out of Developer Technical Support (DTS), producing technical notes to fix or append the
information in various volumes of Inside Macintosh continues to this day. But Technotes, like everything else, are evolving and changing from the old model.
The "Old" New Macintosh Technical Notes
The old Notes continue to live for developers, both on the Web and on Developer CDs. The old Notes have historical value and many are still very useful to Apple developers. These will be properly archived and kept alive. Some of the old Notes, however, that are no longer useful will be "retired"while others will be updated and revised to meet the new documentation needs of Apple's developers.
New Goals
The primary goal of Technotes is provide developers with the most current and up to date documentation available from Apple, in the most timely fashion, i.e., with first publication on the Web and other online sources. It is also to provide developers worldwide with technical documentation that sets the standard for accuracy, reliability, and usefulness of content.
Finally, the goal is adjust the content and delivery of Technotes to match the needs and feedback of Apple developers.
Revising & Updating Notes
The process of updating and revising these Technotes began early this summer and is still ongoing. It's been no easy task. Apple's Developer Technical Support engineers pitched in and began work on the voluminous body of 350 Notes. In the course of revising the old notes, we've evolved them into a new form that we think works better for developers. The new Technotes are
- more concise and tightly edited
- structured so that the Notes map more closely to that of Inside Macintosh, with About, Using, Reference and Summary sections
- aimed at specific types of Macintosh developers, e.g., those writing drivers for PCI cards, or those who are concerned about certain compilers or memory fragmentation in their code
- focused on programming techniques and approaches that may be useful for Macintosh developers, not just correcting the documentation errors in
Inside Macintosh (although that process still continues)
- made searchable on the Web, using a powerful new search engine that indexes the content of the Notes, performs Boolean searches and returns relevance rankings on Notes searched
- updated on a regular basis, at least quarterly, if not more frequently
- open to contributions, when appropriate, from Apple developers worldwide, although it should be noted that a contribution of a Technote does not automatically guarantee its publication
If you're interested in writing or contributing a Technote, we want to hear from you. Or if you have comments and criticisms
of this new approach, please contact us at TM@ applelink.apple.com.
Some Structural Things to Know, a Checklist
In editing your current draft, not all of the following comments will be relevant (some of the sections described may not need to exist in your Technote, and some of the styles we discuss may already be incorporated in your Technote).
Use this as a checklist as you work on the next draft (or first draft, as the case may be) of your Technote:
Writing with Your Favorite Word Processor
It's no longer necessary to produce a Technote using Microsoft Word with a particular Technote template. Use the word processor of your choice. ClarisWorks 4 is a good choice because you can use text in different colors for editing and review. You also can import graphics, even QuickTime movies into your Technote.
Mapping to Inside Macintosh
The structure of Technotes now maps as closely as possible to the structure of the Inside Macintosh volumes.
We're trying to stick consistently to the term "Technotes" throughout. Please note occurrences of the terms "Technical Note," "Technote," etc. and change them accordingly.
There are 4 heading levels. The first one is specifically for certain sections. The others are to create a hierarchy of information which will clarify the overall picture for the reader -- to be used at your discretion.
Writing with the New Technote Structure
Title
(The title is critically important for any Technote because that's how the Note will often be searched, retrieved and ultimately remembered or referred to.)
by
(your name)
(your e-mail address)
Apple Developer Technical Support, Apple Engineering, or the name of your company or organization
Intro Text
This Technote (explains, describes, discusses, clarifies) _____. This should be no longer than one or two paragraphs and provide the reader with an overview of your subject.
Audience To Whom You're Writing
This Technote is directed primarily at (developers working with, for example, QuickTime 2.1 movies and music architecture).
Cross-References
See Inside Macintosh:______ for further documentation.
About (Heading Level 1)
Use subsections, if necessary.
Using (Heading Level 1)
How-to, creating, building, with examples and sample code to illustrate the main point, etc.
Reference (Heading Level 1)
- 1. Function Name
- 2. sentence description of what it does
- 3. How it is used ( in context)
- 4. Explanation of terms
- 5. DESCRIPTION
- 6. ERROR CODES
- 7. SEE ALSO
Summary (Heading Level 1)
This summarizes the main points in your Technote. This is what you want your readers to come away from your Technote knowing and understanding.
Further References (Heading Level 2)
(a bulleted list)
Change History (Heading Level 3)
Originally written in (month, year), by (author).
Since (month, year), (explain changes made).
Technotes
Techeditor
