915736 - [app manager] Write documentation

Status: RESOLVED FIXED

(DevTools Graveyard :: WebIDE, defect)

Description

[Paul Rouget [:paul]]

I started:

https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Using_the_App_Manager

It's important because we link this page in different part of the UI.

If the URL is wrong, please let me know.

Comment 1

[Jean-Yves Perrier [:teoli]]

Adding the people the most likely to help on this in cc: :-)

Thanks Paul!

Comment 2

[Paul Rouget [:paul]]

See also bug 916110.

Comment 3

[Chris Mills [:cmills]]

This is great - thanks Paul! This is a perfect place to put the article. I've added a link to it from https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS, and I'd be glad to help you write this up. Do you want to add the raw information, and then I'll copy edit it polish it up into a final article?

Comment 4

[Paul Rouget [:paul]]

(In reply to Chris Mills from comment #3)
> This is great - thanks Paul! This is a perfect place to put the article.
> I've added a link to it from
> https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS, and I'd be glad
> to help you write this up. Do you want to add the raw information, and then
> I'll copy edit it polish it up into a final article?

Hi Chris. I just updated the documentation. I think it's a bit better. Can you take a look? Also, it's important to keep the anchors. They are used from the Help section in the App Manager (chrome://browser/content/devtools/app-manager/help.xhtml).

Comment 5

[Paul Rouget [:paul]]

Not blocking bug 912913 anymore. The documentation is "good enough".

Comment 6

[Chris Mills [:cmills]]

Great work Paul. Myself or Will Bamberg will get to this very soon.

Comment 7

[Chris Mills [:cmills]]

Ok, I've started on this, but it's taking a while. I failed to get B2G 1.2 built for Keon, but then I found out that you can't build for Keon on Mac.

I then got it built for Arm emulator, but then discovered that there is no way you can get FxOS running on an emulator connecting to the app Manager.

I then tried the simulator (https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Using_the_App_Manager#Simulator), but it doesn't seem to work (I'm using Nightly, v27, on MacOSX.)

Now I've installed Ubuntu on my PC and will try building 1.2 for my Keon on there.

Just to keep you informed of progress ;-)

Comment 8

[Paul Rouget [:paul]]

If you have a Keon, just get a build there: http://downloads.geeksphone.com/keon_nightly/latest_master.html (works on Mac).

Comment 9

[Chris Mills [:cmills]]

Awesome, that worked fine. Getting on with it now.

Comment 10

[Chris Mills [:cmills]]

Ok - I've given the article a thorough edit/test run, throughout the course of today. See https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Using_the_App_Manager

For the moment, I have just put in rough images, as I wanted feedback before making neat final ones. Are they too small, are they the right ones, etc.?

Have a good read through and let me know if you want any more changes made, and if I have kept the meaning of your original text?

I did also have some specific feedback on the article, that will need answering before I then make some more changes:

1. the adb helper add-on doesn't seem to exist. the link returns "not found"

2. Aren't the terms packaged app and hosted app used incorrectly? Surely it should be local app or external app? You could have packaged and hosted apps, externally or locally.

3. Note the bug I've written about in the article:

"Note: When you connect to the simulator it selects a random unused port to connect via. Currently, however, when you disconnect the simulator connection it causes the port to connect to the real device via to be set to that port as well. You will see the "Connect to localhost:XXXX" button label updated to reflect this. This means that connecting to a real device then won't work, unless you use the "Change" button to change the port number back again, or update port forwarding for this port as well, as instructed in the {{anch("Enable port forwarding")}} section, above. We should fix this issue soon."

4. When you connect to a device, and the prompt appears on the device for the remote debugging request to be accepted, the screen stays dark if it is already powered down. It would be better to power up the screen again once then request is received, as it is quite easy to miss. Is this possible?

5. Can you link to actual IDs from the app, rather than from the <a name=""></a> elements you have inserted? They make ugly boxes appear around the headings, which could be avoided ;-)

Comment 11

[Paul Rouget [:paul]]

Thank you Chris. This is excellent! Comments inline.

(In reply to Chris Mills from comment #10)
> Ok - I've given the article a thorough edit/test run, throughout the course
> of today. See
> https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/
> Using_the_App_Manager
> 
> For the moment, I have just put in rough images, as I wanted feedback before
> making neat final ones. Are they too small, are they the right ones, etc.?
> 
> Have a good read through and let me know if you want any more changes made,
> and if I have kept the meaning of your original text?

About the `ADB or ADB helper`, we want to encourage to install the addon first. ADB Helper should be the first thing to do. If it doesn't work, suggest the original ADB method.

In "Enable port forwarding", we should mention that it's needed everytime the phone is restarted or unplugged then re-plugged.

We use the work "connect" a little too much. Connect means so many things in this context that it gets confusing (connecting via USB, then connect ADB via ADB, then connect with the app manager). "Connect the device to your computer via USB" should say "Plug the device".

In the "Connecting your device to the App Manager" section, make sure to say when operations happen on the phone or not.

> 
> I did also have some specific feedback on the article, that will need
> answering before I then make some more changes:
> 
> 1. the adb helper add-on doesn't seem to exist. the link returns "not found"

Yeah. We're running into some issues with AMO. We hope to fix that soon.

> 2. Aren't the terms packaged app and hosted app used incorrectly? Surely it
> should be local app or external app? You could have packaged and hosted
> apps, externally or locally.

They are used correctly. But I have to admit it's confusing:
From the point of view of Firefox OS, an app can be installed on the sdcard (packaged app) or located remotely (hosted app). When the user click on the icon, the page is loaded from the sdcard or from the network.
On the App Manager an app is on the hard drive (local) or on the network (remote). A local app will be packaged and a remote app will be hosted.

Is that clear?


> 3. Note the bug I've written about in the article:
> 
> "Note: When you connect to the simulator it selects a random unused port to
> connect via. Currently, however, when you disconnect the simulator
> connection it causes the port to connect to the real device via to be set to
> that port as well. You will see the "Connect to localhost:XXXX" button label
> updated to reflect this. This means that connecting to a real device then
> won't work, unless you use the "Change" button to change the port number
> back again, or update port forwarding for this port as well, as instructed
> in the {{anch("Enable port forwarding")}} section, above. We should fix this
> issue soon."

Known issue we want to fix in Aurora: bug 917479.

> 4. When you connect to a device, and the prompt appears on the device for
> the remote debugging request to be accepted, the screen stays dark if it is
> already powered down. It would be better to power up the screen again once
> then request is received, as it is quite easy to miss. Is this possible?

Bug 914557.

> 5. Can you link to actual IDs from the app, rather than from the <a
> name=""></a> elements you have inserted? They make ugly boxes appear around
> the headings, which could be avoided ;-)

I don't understand that.

Comment 12

[Chris Mills [:cmills]]

Thanks for the comments Paul. I'll get more fixes made next week, for sure.

Comment 13

[Paul Rouget [:paul]]

FYI, I made some changes (better link for simulator and updated the prefs.js command).

Comment 14

[Paul Rouget [:paul]]

I added a "Quick Setting" section.

Comment 15

[Paul Rouget [:paul]]

I added some big "install" buttons for both addons.

Comment 16

[Paul Rouget [:paul]]

The screenshot are low quality. Chris, can you fix that?

Comment 17

[Chris Mills [:cmills]]

I've gone through and made all the changes you requested in the comments, apart from dealing with the screenshots. I made them small because the main content columns on the new MDN theme are narrower than they used to be.

But I'll work on a way around this - I can always retake the screenshots using smaller browser windows, so the details appear bigger. I'll do this tomorrow.

Comment 18

[Chris Mills [:cmills]]

New screenshots added. These look a lot better, and are more readable.

Let me know if you want any more updates.

Comment 19

[Paul Rouget [:paul]]

Looks good! Thanks Chris.