838831 - Turn /Apps/Reference into API docs landing page and move to /Apps

Status: RESOLVED FIXED

(Developer Documentation Graveyard :: Apps, defect)

Description

[Fred Wenzel [:wenzel]]

https://developer.mozilla.org/en-US/docs/Apps/Reference is a great start on an API docs landing page.

Before MWC, the following things should happen:
- Turn it into a landing page. The top of the page should ask first-time visitors to get started at the developer hub, before going on to list all the great APIs and stuff like it is right now. CCing tsmuse for input on what that should look like.
- Content review -- let's publish the page to a few apps developers (Robert, tofumatt, etc.) to make sure we're hitting the right API docs in the list.
- Move this page to /Apps in place of the page that's currently there.

Does that sound reasonable?

Comment 1

[Eric Shepherd [:sheppy]]

This page is not really suitable as a landing page as it is. Next week, however, we will be cleaning up the Apps landing page to make it less forbidding to look at, which will probably accomplish the goal you have in mind.

Comment 2

[Fred Wenzel [:wenzel]]

Let's have Tony suggest what the landing page should look like that's consistent with the other IA work he's been doing in bug 832531.

Comment 3

[Tony Santos [:tsmuse]]

What we're really concerned with here is duplicating info across the two sites (Dev Hub and MDN's apps section) and ending up with a situation where developers don't really know where to go to find the answers they need to develop their apps. In the short-term (for MWC) we believe the best way to achieve this is to say "Dev hub is the entry point in to the 'Making Apps' experience" and "MDN is the source for technical documentation for making apps." (This is not a great long-term solution, I admit, but there are a lot more discussions around the MDN redesign that's underway and the role that Dev Hub plays in the developer documentation experience that need to be had for a great long term solution to come into existence.)

So here's what we are proposing for the short term:

Dev hub will absorb and be the sole source for the following articles, while keeping all links back to MDN for technical details intact:
* App development for mobile application developers
* App development for Web developers
* Using apps offline
* Developing game apps
* Open Web Apps and Web standards

Dev hub will remove it's pages and simply offer links to MDN  articles via the reference page (see details below) for the following existing Dev hub topics:

* Manifests (building a Manifest details)

MDN will remove/hide the following articles that exist today on Devhub:
* Submitting an app
* Marketplace review criteria
* Getting started with making web apps (this info will be covered in the new "Quick Start" page)

New topics that will live in MDN and only be linked to by Devhub:

* ALL API docs
     
All Dev hub pages will have a "References" link (I'm totally open to a better name if anyone has one) that will link to https://developer.mozilla.org/en-US/docs/apps. We are hoping this page will be able to function much as it is currently, as a portal into more detailed information about building open web apps, but without the overlap of the more general "intro" articles on Dev hub.

Comment 4

[ali spivak]

I think this is a good plan for the short term. Let's meet after MWC and come up with a long-term strategy. 

for now - let's get this done ASAP - it needs to be finished be Feb 20.

Comment 5

[Michael Morgan [:morgamic]]

FYI - I've asked Tony and Holly to meet about longer-term plans for IA/Content.  That should get us off on the right foot for post-MWC work.  I'm excited about what we'll be able to accomplish together the rest of the year.

Comment 6

[Fred Wenzel [:wenzel]]

Eric, do you know how to proceed, or do you need more guidance from Tony?

Deadline for the items in comment 3 to be live in production is Thursday, Feb 21. Thanks!

Comment 7

[Eric Shepherd [:sheppy]]

I think I'm good to go. On it.

Comment 8

[John Karahalis [:openjck]]

Sounds like this does not involve development work, so I am moving this over to the "Developer Documentation" product. Please correct if wrong.

Comment 9

[Daniel Buchner [:dbuc]]

(In reply to Eric Shepherd [:sheppy] from comment #7)
> I think I'm good to go. On it.

I'm not seeing the described changes on the page: https://developer.mozilla.org/en-US/docs/Apps/Reference

When are we going to get the stuff Fred specified added to this so we can link it from Dev Hub?

Comment 10

[John Karahalis [:openjck]]

Adding a needinfo as per comment 9.

Comment 11

[ali spivak]

Hi all, if needed to sort this out, please have a call. The API reference has been assigned to Mark, the Apps pages sheppy should keep point on.

Comment 12

[Eric Shepherd [:sheppy]]

(In reply to Daniel Buchner [:dbuc] from comment #9)
> (In reply to Eric Shepherd [:sheppy] from comment #7)
> > I think I'm good to go. On it.
> 
> I'm not seeing the described changes on the page:
> https://developer.mozilla.org/en-US/docs/Apps/Reference
> 
> When are we going to get the stuff Fred specified added to this so we can
> link it from Dev Hub?

I'm confused. I spent a week rebuilding the entire Apps subtree to cover all of these topics. That's not good enough?

This "Reference" page was meant to be a temporary placeholder until the new hierarchy was built. That's done now, so it seems to me this is finished. What still needs to be done?

Comment 13

[Michael Morgan [:morgamic]]

Sheppy - I appreciate the time you spent on the content re-org.

As far as I can tell, this is not what we had agreed on.  We needed to move the documents in comment #3 over and have them as a part of a branded landing experience for webdevs at MWC.  That ship has sailed already -- we agreed to do the short-term fix to buy time for Holly and Tony to figure out IA/UX long-term.

Not sure where the disconnect happened but please re-read this bug and bug 835574 - Daniel or someone else is available to chat real-time if you have questions.

Tony's assessment of our information architecture in bug 835574 is still solid, and over the short term consolidation of content on devhub is our easiest path to victory.  That plus the need for cohesive branding and a smooth hand-off with marketplace submission were the two pulls for devhub.

That said, we need focus on API docs.  The point of this bug and our discussions was to get more focus on WebAPIs because those are so important to developers.  The content hierarchy we were solving separately by implementing devhub as a landing/catch-all for apps devs in the MWC timeframe.  That was the point of Tony's UX/IA work.

So I don't think this work is finished yet...  at least not in context with comment #3.

Dan/Tony - any comments?

Comment 14

[Michael Morgan [:morgamic]]

Tony and Dan will list the tweaks/changes that are left.  In the meantime Sheppy the API and Design docs to focus on.  I asked Tony and Dan to help with editing as well to help out.

Comment 15

[Fred Wenzel [:wenzel]]

Assigning to tsmuse per comment 14.

Comment 16

[Tony Santos [:tsmuse]]

Here are the changes I made, per my earlier plan listed in comment 3, that we all agreed to:

* Added a link and description to the Firefox OS Apps quick-start guide on Devhub
* Changed link for  App Development for Current Web Developers page to point to the Devhub version of that page
* Changed link for App Development for Current Mobile App Developers page to point to the Devhub version of that page
* Changed link for Developing Game Apps page to point to the Devhub version of that page
* Changed link for Using your App offline to point to the Devhub version of that page
* Changed link for Using App Templates to point to the Devhub App Generator templates page
Changed link for Packaged Apps to point to the Devhub version of that page


These changes keep us cross-linked and inline with the idea (for MWC at least) that Devhub is where you go to learn about Firefox OS and Open Web Apps and get the basic overview, and MDN is the technical reference source for developers.

Comment 17

[Fred Wenzel [:wenzel]]

All right, marking this fixed for now. For all other adjustments we need to regroup.