Bug613576 - create introductory initial page for SDK documentation; r…

…=myk
mozilla · Dec 3, 2010 · 19b79b8 · 19b79b8
1 parent 997f3a8
commit 19b79b8
Show file tree

Hide file tree

Showing 4 changed files with 93 additions and 21 deletions.
diff --git a/static-files/index.html b/static-files/index.html
@@ -18,46 +18,48 @@
   <div id="columns">
   <div id="left-column">
     <h1>Add-on SDK Docs</h1>
+
+    <h2  class="link" "section" id="welcome">Home</h2>
+
     <h2 id="dev-guide-header">Developer Guide <a id="hide-dev-guide-toc">hide</a></h2>
 
     <div id="dev-guide-toc">
-
       <div class="section" id="tutorial-header">Tutorial</div>
       <ol id="tutorials">
-        <li id="getting-started">Getting Started</li>
-        <li id="packaging">Packaging</li>
-        <li id="programs">Programs</li>
-        <li id="events">Working with Events</li>
-        <li id="web-content">Working with Content Scripts</li>
+        <li class="link" id="getting-started">Getting Started</li>
+        <li class="link" id="packaging">Packaging</li>
+        <li class="link" id="programs">Programs</li>
+        <li class="link" id="events">Working with Events</li>
+        <li class="link" id="web-content">Working with Content Scripts</li>
       </ol>
 
       <div class="section" id="experimental-header">Experimental</div>
         <ol id="experimental">
-          <li id="xul-extensions">Using the SDK with XUL extensions</li>
+          <li class="link" id="xul-extensions">Using the SDK with XUL extensions</li>
         </ol>
 
       <div class="section" id="internals-header">Internals</div>
         <ol id="internals">
-          <li id="best-practices">Low-Level Module Best Practices</li>
-          <li id="chrome">Chrome Authority / Manifest Generation</li>
-          <li id="xpi">XPI Generation</li>
-          <li id="internal-globals">Internal Globals</li>
+          <li class="link" id="best-practices">Low-Level Module Best Practices</li>
+          <li class="link" id="chrome">Chrome Authority / Manifest Generation</li>
+          <li class="link" id="xpi">XPI Generation</li>
+          <li class="link" id="internal-globals">Internal Globals</li>
         </ol>
 
       <div class="section" id="reference-header">Reference</div>
         <ol id="reference">
-          <li id="globals">Globals</li>
-          <li id="cfx-tool">cfx Tool</li>
-          <li id="package-spec">Package Specification</li>
-          <li id="glossary">Glossary</li>
-          <li id="program-id">Program ID</li>
-          <li id="troubleshooting">Troubleshooting</li>
+          <li class="link" id="globals">Globals</li>
+          <li class="link" id="cfx-tool">cfx Tool</li>
+          <li class="link" id="package-spec">Package Specification</li>
+          <li class="link" id="glossary">Glossary</li>
+          <li class="link" id="program-id">Program ID</li>
+          <li class="link" id="troubleshooting">Troubleshooting</li>
         </ol>
 
       <div class="section" id="appendices-header">Appendices</div>
       <ol id="appendices">
         <li><a href="https://wiki.mozilla.org/Labs/Jetpack/Release_Notes">Release Notes</a></li>
-        <li id="credits">Credits</li>
+        <li class="link" id="credits">Credits</li>
       </ol>
 
     </div>

diff --git a/static-files/js/main.js b/static-files/js/main.js
@@ -5,7 +5,7 @@ function startApp(jQuery, window) {
   var currentHash = "";
   var shouldFadeAndScroll = true;
 
-  const DEFAULT_HASH = "guide/getting-started";
+  const DEFAULT_HASH = "guide/welcome";
   const IDLE_PING_DELAY = 500;
   const CHECK_HASH_DELAY = 100;
 
@@ -429,7 +429,7 @@ function startApp(jQuery, window) {
   }
 
   function linkDeveloperGuide() {
-    $("#dev-guide-toc li").each(
+    $(".link").each(
       function() {
         if ($(this).children().length == 0) {
           var hash = "#guide/" + $(this).attr("id");

diff --git a/static-files/md/dev-guide/getting-started.md b/static-files/md/dev-guide/getting-started.md
@@ -1,4 +1,3 @@
-Welcome to the Add-on SDK.
 
 Prerequisites
 -------------

diff --git a/static-files/md/dev-guide/welcome.md b/static-files/md/dev-guide/welcome.md
@@ -0,0 +1,71 @@
+
+# Welcome to the Add-on SDK #
+
+The Add-on SDK is designed to make it easy to develop Firefox add-ons.
+
+It includes:
+
+* a set of ***modules*** providing high-level JavaScript APIs which you can use
+to create add-ons. These modules simplify tasks such as building a user
+interface and interacting with the Web, and will help ensure your add-on
+continues to work as new versions of the host application are released.
+
+* a set of ***tools*** for creating, running, testing, and packaging add-ons
+
+The documentation is divided into two parts: the Developer Guide and the
+Package Reference. The Developer Guide is a collection of documents explaining
+how to use the tools and APIs, while the Package Reference includes
+detailed documentation for each module API.
+
+## Developer Guide ##
+
+* The [***Tutorial***](#guide/getting-started) is probably the best place to
+start: it explains how to install the SDK, takes you through the process of
+writing a simple add-on and introduces some of the main APIs.
+
+* The ***Reference*** section provides some more in-depth documentation for
+various aspects of the SDK.
+
+* The ***Experimental*** section includes documentation of features which are
+potentially useful to add-on developers but are not yet stabilised.
+
+* The ***Internals*** section includes documentation which is more likely to
+be useful to people extending the SDK itself than to add-on developers. In
+particular, it contains important information for people developing modules
+which require privileged access to browser objects such as the chrome. If you
+are interested in helping to extend the SDK, then this section should be
+useful.
+
+## Package Reference ##
+
+The Package Reference provides detailed API documentation for the modules
+supplied in the SDK. The SDK follows the [CommonJS](http://www.commonjs.org/)
+standard according to which modules - pieces of reusable JavaScript - are
+collected into packages. There are two main packages.
+
+* The ***addon-kit*** package provides high-level APIs for add-on developers.
+Most of the needs of most add-on developers should be served by the modules
+found here, and the bulk of the developer guide is dedicated to modules from
+this package. Modules in this packages also don't require any special
+privileges to run.
+
+* The ***api-utils*** package provides low-level APIs. Most of the modules it
+contains are intended for people writing certain specific types of add-ons, and
+for people writing their own reusable modules. In particular it contains
+modules that supply basic services, like messaging, for higher-level modules.
+Many of the modules in this package require privileged access to the browser
+chrome.
+
+## Stability and Compatibility ##
+
+The different categories listed above also reflect differences in the stability
+of the different parts of the SDK.
+
+Features and APIs documented in the ***Tutorial*** and ***Reference***
+sections, and the modules in the ***addon-kit*** package, are relatively
+stable. We intend to add new APIs here and extend existing ones, but will
+avoid making incompatible changes to them unless absolutely necessary.
+
+Features and APIs documented in the ***Experimental*** and ***Internals***
+sections, and the modules in the ***api-utils*** package, are less stable and
+we expect to make incompatible changes to them in future releases.