560656 - Come up with some documentation conventions

Status: RESOLVED FIXED

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

Description

[Drew Willcoxon :adw]

Some docs do everything in Markdown (most), others use the <api> syntax (#module/jetpack-core/url); some docs use tables to explain the keys of options objects, others use lists; some docs start by listing constructors and functions, others are more freestyle...

We should settle on conventions so people don't have to parse inconsistencies when they're learning and looking up info.  Especially for high-level APIs.  I'm not arguing that every doc should be structured exactly the same, but there should be consistency where appropriate.  The <api> syntax doesn't even produce a style that's consistent with most of the other docs.

Comment 1

[Atul Varma [:atul]]

I think I helped start this mess, so I'll coordinate with Noelle, Luca and folks on the google group to figure out what to do about it.

Thanks for bringing this up!

Comment 2

[Atul Varma [:atul]]

At the weekly meeting today Myk mentioned Noelle will be doing this, so re-assigning to her. Thanks for taking this on, Noelle!

Comment 3

[Dietrich Ayala (:dietrich)]

Hi Noelle, what's the status of this? If there are conventions we should be using, can you note them on the wiki somewhere and add the link here?

Comment 4

[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".

Comment 5

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

This seems to have become a tracking bug for a bunch of changes that have already occurred, so marking fixed (modulo one remaining bug that can be tracked individually).