566493 - doc changes that will be included in 0.4 for the jetpack sdk

Status: RESOLVED FIXED

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

Description

[Noelle Murata]

Attachment: jetpack-sdk docs structure changes for 0.4

This is an interim step for the documentation restructure. Leaving most of the developer written docs as they are, but modifying the structure.

See attachment for details on structural modification.
* adding a section describing the folder hierarchy

Comment 1

[Noelle Murata]

Attachment: jetpack-sdk docs structure changes for 0.4 patch proposal

Comment 2

[Noelle Murata]

Attachment: diff against central repo

Comment 3

[Noelle Murata]

Attachment: new repo diff on central repo

Comment 4

[Noelle Murata]

Attachment: new diff against central repo

Comment 5

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

Comment on attachment 445874 [details] [diff] [review]
new diff against central repo

This patch applies just fine and looks pretty good!  There are just a few terminology issues, noted below...


>diff -r a9924484005f -r 2271967854a4 static-files/index.html

>+        <li id="jetpack-sdk-folders">Jetpack SDK Folder Map</li>

"Jetpack SDK" seems redundant in this section name, as everything in the docs is related to the Jetpack SDK, so this would be better as simply "Folder Map".

Also, the docs use "directory" rather than "folder" almost everywhere else.  To be consistent, it should use "directory" here as well (and in the map doc itself, both in its name and in its text), i.e. Directory Map.


>diff -r a9924484005f -r 2271967854a4 static-files/md/dev-guide/jetpack-sdk-folders.md

>+* bin:  This folder contains executable scripts for command line use.

Nit: here and in the rest of the document, "this folder contains", "this is", and "this package contains" seem unnecessary, and they make the document significant more verbose.  I recommend leaving them out in favor of simply:

  * bin:  executable scripts for command line use.

Also, it'd be good to make the directory/file names stand out from their descriptions with some style (bold, italics, etc.).


>+* python-lib:  This folder contains the core python libraries for operating the jetpack framework. 

Nit: python -> Python
Nit: jetpack -> Jetpack


>+* packages:  This is the main packages directory. Core packages as well a new
>+packages live here.

Nit: a new packages -> new packages

Also, I don't think folks are going to know what "new packages" means, so this should say something like "core packages as well as packages you obtain from others and those you create yourself live here."


>+    * jetpack-core:  This package contains jetpack libraries, tests, documentation and package definition.

The use of the directory name "lib" confuses things a bit, but "jetpack-core" actually doesn't contain a library.  Rather, it is a library (which is just a kind of package) that contains modules (which live in the lib/ subdirectory) along with their related unit tests, docs, etc., and package.json is best described as a manifest file, so this should say something like:

    * jetpack-core: core Jetpack modules along with their unit tests, documentation, and manifest.

Alternately, you could say something like this:

    * jetpack-core: core library, including unit tests, documentation, and manifest.


>+        * docs: This contains the Markdown files documenting the APIs. 
>+        * lib: This contains the JavaScript libraries. 

libraries -> modules


>+        * tests: This contains test files. 

test -> unit test


>+        * package.json: This is the package description for the library.

package description -> manifest


>+    * development-mode:  This package contains the development-mode library and
>+    package definition. 
>+    * test-harness:  This package contains the test harness library, tests, documentation and package definition.

library -> modules (or rephrasing, as per jetpack-core suggestions above)

package definition -> manifest

Comment 6

[Noelle Murata]

Attachment: with latest fixes per Myk's comment, vs central repo

Comment 7

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

Comment on attachment 445895 [details] [diff] [review]
with latest fixes per Myk's comment, vs central repo

Looks good, r=myk!

The one nit I just noticed is the name of the directory map file, which should use "directories" instead of "folders" and doesn't need "jetpack-sdk" in its name (since, as with the entry in the Table of Contents, it's obvious that it applies to the Jetpack SDK, as all the docs files do so).

So it can be called something like just directories.md.  I'll fix that on checkin.

Comment 8

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

Fixed by changeset https://hg.mozilla.org/labs/jetpack-sdk/rev/6555e5b96c12.  Thanks Noelle!

Comment 9

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

The Add-on SDK is no longer a Mozilla Labs experiment and has become a big enough project to warrant its own Bugzilla product, so the "Add-on SDK" product has been created for it, and I am moving its bugs to that product.

To filter bugmail related to this change, filter on the word "looptid".