Re: New API reference docs structure plan

[Chris Mills]

Here is my attempt at a new standard for API landing pages:

https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API

I’ve moved the IndexedDB pages to the correct positions, and reorganized the landing page to provide quicklinks to all the most important guides and interface references (A-Z), and key concepts, examples, and Interfaces arranged by topics in the main body.

Chris Mills
Senior tech writer || Mozilla
developer.mozilla.org || MDN
cmi...@mozilla.com || @chrisdavidmills



On 3 Apr 2014, at 19:02, Eric Shepherd <eshe...@mozilla.com> wrote:

> We had a quick meeting today to settle out a plan for the structure of the API reference docs, and here's what we came up with:
>
> Web/API: Landing page for all Web API docs. The layout of this page is TBD; the five of us that attended the meeting are each going to mock up a proposal to share in a couple of weeks.
>
> Each API then gets a landing page under this:
>
> Web/API/DOM
> Web/API/File_API
> Web/API/IndexedDB_API
> ... etc ...
>
> Those landing pages then have subpages with tutorials and guide content:
>
> Web/API/File_API/Intro
> Web/API/File_API/Reading_binary_files
> ... whatever ...
>
> All interface reference documents are located directly under Web/API:
>
> Web/API/IDBIndex
> Web/API/FileReader
> ... etc...
>
> (that means they stay where they are now, the ones that are already under Web/API)
>
> It's crucial that tagging standards be adhered to; in particular:
>
> * Reference pages must be tagged "Reference" plus with the appropriate tag identifying the individual API the interface is part of. A list of these tags will be made available soon, but they're also provided in the "Tagging standard" section of each Documentation status page.
>
> * Landing pages must be tagged "Landing" plus the tag identifying the individual API.
>
> These individual API landing pages' designs will also be mocked up by each of the people that were at today's meeting, with their designs presented in another meeting in a couple of weeks.
>
> Those designs will be considered and proposals presented here as well as to other teams for review and improvements before we start using them.
>
> In the interim, we will use temporary quick lists of relevant pages on each landing page to get the job done.
>
> Some thought son the landing pages for each API, as to the types of things we hope to include:
>
> * A quick way to get solutions to specific problems (I'm trying to X... so you should do Y).
>
> * An alphabetical list of the interfaces for that API.
>
> * Categorized lists of interfaces ("Reading files", "Writing files", "Hunting snipes", watever)
>
> A similar type of concept will apply to the overall API landing page:
>
> * Problem--> solution finder
>
> * List of APIs alphabetically
>
> * Categorized lists of APIs
>
> * A link to the alphabetized "all interfaces" page
>
> Any concerns about this plan? If so, speak now or forever hold your peace, because work on moving pages will begin imminently. :)
>
> --
> Eric Shepherd
> Developer Documentation Lead
> Mozilla
> Blog: http://www.bitstampede.com/
> Twitter: @sheppy
>
> _______________________________________________
> dev-mdc mailing list
> dev...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-mdc

[Chris Mills]

On the train today I put together a quick Balsamiq mockup - some ideas for the MDN API landing page:

http://people.mozilla.org/~cmills/temp/API_landing_page_mockup.png

Before I argued that we shouldn’t have separate landing pages for each API category, but now I’m reconsidering, as there will be so many APIs to list.

Chris Mills
Senior tech writer || Mozilla
developer.mozilla.org || MDN
cmi...@mozilla.com || @chrisdavidmills

[Ali Spivak]

Looks good - I like it.

I like idea of having a targeted search on the page as well


ali spivak
408-859-8260
asp...@mozilla.com

[Chris Mills]

This is cool sheppy. Quite similar to mine, but better laid out search boxes. I like the layout of those.

I think one of the main question here is whether we have separate landing pages for each API category. I would rather not, but reckon we might need to, as there will be so many to list on that page otherwise.

Chris Mills
Senior tech writer || Mozilla
developer.mozilla.org || MDN
cmi...@mozilla.com || @chrisdavidmills

On 8 Apr 2014, at 17:01, Eric Shepherd <eshe...@mozilla.com> wrote:

> And here's my mockup proposal for the Web/API landing page: http://www.bitstampede.com/files/mdn/APIMainPage.png
>
> Comments welcome!

>
> Eric Shepherd
> Developer Documentation Lead
> Mozilla

> http://www.bitstampede.com/

[Ali Spivak]

I think, from a usability standpoint, we might need to. There are a LOT of API's (& 300 pages of sub-content)

Also, can we thinkof scenariois where we might need to link to a category page (e.g. Device API's) and not to the main overview page?

ali spivak
408-859-8260
asp...@mozilla.com

----- Original Message -----
From: "Eric Shepherd" <eshe...@mozilla.com>
To: "Chris Mills" <cmi...@mozilla.com>
Cc: dev...@lists.mozilla.org
Sent: Tuesday, April 8, 2014 11:28:40 AM
Subject: Re: New API reference docs structure plan

Chris Mills wrote:
> I think one of the main question here is whether we have separate landing pages for each API category. I would rather not, but reckon we might need to, as there will be so many to list on that page otherwise.

I agree; I'd prefer not to have them for the categories.

--

Eric Shepherd
Developer Documentation Lead

Mozilla Corporation
Blog: http://www.bitstampede.com/

[Chris Mills]

On 8 Apr 2014, at 19:39, Ali Spivak <asp...@mozilla.com> wrote:

> I think, from a usability standpoint, we might need to. There are a LOT of API's (& 300 pages of sub-content)
>
> Also, can we thinkof scenariois where we might need to link to a category page (e.g. Device API's) and not to the main overview page?

Device APIs, definitely. I’ve got so many calls to do this on the App Center/Firefox OS pages ;-)

Others…hrm.

[Francesco Iovine]

Hi all,

> Others...hrm.
>

Hmm, I think I can help here :)

First of all, I like the search tool and the alphabetical index, and agree
with Ali (there are a lot of APIs, we might need categories) and with Chris
and Sheppy (I'd prefer not to have separate pages for categories). Existing
categories (Communication, Hardware access, Data management) are ok, but I
don't like the "Other APIs" category and the fact there's no mention of
Media* APIs.

About Device APIs I noticed a difference in terminology between the W3C [1]
and MDN [2]: MDN does not mention "Device APIs" at all, and W3C includes
Media* APIs in Device APIs for example, while MDN provides a WebRTC section
for them [3]. I think that introducing the term "Device APIs" in the WebAPI
landing page [2] might mean "standard APIs which interact with device
services", which is a quite generic description. From this point of view,
other categories might be "non-standard APIs", "installed / privileged
APIs", "certification-required APIs". Hmm.. categorizing is hard..

As for the other landing pages, I like the idea of introducing workflow
diagrams, FAQs and use cases, which are maybe best-suited for describing
specific APIs (the "Guides and samples" section in sheppy's mockup on
Battery API is in step with this).

For the WebAPI landing page, after introducing the search tool and the
alphabetical index, there might not need of a (categorized) list of APIs
anymore; and scenarios, as Ali suggested, might be added to provide a
comprehensive overview of what Web APIs are for and which ones can be used
in specific contexts (application types, supported platforms/browsers,
supported devices in term of hardware/sensors needed to make the API work,
etc.), and highlighting what is fully supported/standardized or very cool
in FirefoxOS :)

Hope it helps! (and makes sense :)

Francesco <https://developer.mozilla.org/en-US/profiles/franciov>

[1] http://www.w3.org/2009/dap/
[2] https://developer.mozilla.org/en-US/docs/WebAPI
[3] https://developer.mozilla.org/en-US/docs/WebRTC

[Francesco Iovine]

Hi Chris,

this is the W3C page I was telling you about in Rome:

http://www.w3.org/Mobile/mobile-web-app-state/

It provides a good categorization for WebAPI.

Hope it helps!

Francesco <https://developer.mozilla.org/en-US/profiles/franciov>

On 9 April 2014 16:45, Francesco Iovine <f.io...@gmail.com> wrote:

> Hi all,
>
> On 8 April 2014 20:43, Chris Mills <cmi...@mozilla.com> wrote:
>
>>
>> On 8 Apr 2014, at 19:39, Ali Spivak <asp...@mozilla.com> wrote:
>>
>> > I think, from a usability standpoint, we might need to. There are a
>> LOT of API's (& 300 pages of sub-content)
>> >
>> > Also, can we thinkof scenariois where we might need to link to a
>> category page (e.g. Device API's) and not to the main overview page?
>>
>> Device APIs, definitely. I’ve got so many calls to do this on the App
>> Center/Firefox OS pages ;-)
>>

>> Others…hrm.