613576 - create introductory initial page for SDK documentation

Status: RESOLVED FIXED

(Add-on SDK Graveyard :: Documentation, defect)

Description

[Myk Melez [:myk] [@mykmelez]]

The initial page to which one is directed when one loads SDK documentation is the first page of the tutorial, which isn't clear and seems strange, given that such collections of documents usually have some sort of introductory page with basic information about the product and an outline of the available documentation along with tips for using it effectively as their initial page.

The SDK documentation should have such an initial page as well.

Comment 1

[Will Bamberg [:wbamberg]]

Attachment: Added intro page to Add-on SDK

Please, feel free to delegate this. I'm never too sure who to ask.

It sort of bugs me that there are no index pages for the sections, so you can't actually link to the "Tutorial", but fixing that is a little involved, given the way the pages are built, and I thought it better to get something out now. In any case this page is a bit of a placeholder given the changes I want to make in the Dev Guide. 

I'm also not crazy about "Home" - I think it matters that the user can get back to this page, but not sure what best to call the link. "Home"? "Welcome"? "About"?

Comment 2

[Myk Melez [:myk] [@mykmelez]]

Comment on attachment 494472 [details] [diff] [review]
Added intro page to Add-on SDK

(In reply to comment #1)
> Please, feel free to delegate this. I'm never too sure who to ask.

There are no rules, and you can ask any reviewer (currently Atul, Brian, Dietrich, Drew, or me).  When changing an existing file (or portion thereof) that was last touched by a reviewer, it can be handy to ask that person for review, since they are likely to know the code the best, but it isn't required.


> It sort of bugs me that there are no index pages for the sections, so you can't
> actually link to the "Tutorial", but fixing that is a little involved, given
> the way the pages are built, and I thought it better to get something out now.
> In any case this page is a bit of a placeholder given the changes I want to
> make in the Dev Guide. 

Yup, makes sense.


> I'm also not crazy about "Home" - I think it matters that the user can get back
> to this page, but not sure what best to call the link. "Home"? "Welcome"?
> "About"?

Start?  Begin?  Introduction?  I'm not sure either.


>diff --git a/static-files/js/main.js b/static-files/js/main.js

>@@ -428,18 +428,18 @@ function startApp(jQuery, window) {
>     });
>   }
> 
>-  function linkDeveloperGuide() {
>-    $("#dev-guide-toc li").each(
>-      function() {
>-        if ($(this).children().length == 0) {
>-          var hash = "#guide/" + $(this).attr("id");
>-          var hyperlink = $('<a target="_self"></a>');
>-          hyperlink.attr("href", hash).text($(this).text());
>-          $(this).text("");
>-          $(this).append(hyperlink);
>-        }
>-      });
>-  }
>+function linkDeveloperGuide() {
>+  $(".link").each(
>+    function() {
>+      if ($(this).children().length == 0) {
>+        var hash = "#guide/" + $(this).attr("id");
>+        var hyperlink = $('<a target="_self"></a>');
>+        hyperlink.attr("href", hash).text($(this).text());
>+        $(this).text("");
>+        $(this).append(hyperlink);
>+      }
>+    });
>+}

This should actually remain indented two spaces, as it is defined inside the startApp function.


>diff --git a/static-files/md/dev-guide/welcome.md b/static-files/md/dev-guide/welcome.md

>+The Add-on SDK is designed to make it easier to develop Firefox and Thunderbird
>+add-ons.

Nit: easier -> easy (as we aren't comparing it to something else here).

Also, although the SDK's architecture was designed to make it possible to build Thunderbird add-ons (and XULRunner applications), and notwithstanding other references to Thunderbird sprinkled through our docs, we haven't spent much time on Thunderbird compatibility, and I'm hesitant to advertise support for it until there is someone in the project who is focused on that support and affirms that we're ready to advertise it, so let's just mention Firefox for now.



>+* The ***Experimental*** section includes documentation of features which we
>+expect might change in incompatible ways in future releases.
>+
>+* 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.

The Internals section should have the same warning as the Experimental section about the possibility of things changing.


>+* 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.

We should put the same "might change" warning on the api-utils package, since we haven't reached the point at which we are ready to declare that it is relatively stable.

And it might be useful to put the opposite kind of statement on the addon-kit package, i.e. to say that we expect its APIs to be relatively stable, in that we will add APIs (and API calls) to it but don't plan to make breaking changes to existing ones.

Comment 3

[Will Bamberg [:wbamberg]]

Attachment: Addressing review comments

I thought having a separate section on stability and compatibility might be clearer and help emphasize the importance of this.

Comment 4

[Myk Melez [:myk] [@mykmelez]]

Comment on attachment 495026 [details] [diff] [review]
Addressing review comments

Looks great, r=myk!

Comment 5

[Drew Willcoxon :adw]

This is great stuff, Will.

Comment 6

[Will Bamberg [:wbamberg]]

Thanks Drew (and Myk)!

Fixed in https://github.com/mozilla/addon-sdk/commit/19b79b8ea2496f6d2fb9b5bed2b84b340f54101c

Comment 7

[Myk Melez [:myk] [@mykmelez]]

Cherry-pick commit:

https://github.com/mozilla/addon-sdk/commit/101e7198553311c6c16afcd11f47abda191de95d