The new app manager has landed (preffed off). We will need to update the documentation. We should wait until all the major features have landed.

Here is a screencast: http://people.mozilla.org/~prouget/webide.webm

Summary of what the new app manager does: https://wiki.mozilla.org/DevTools/WebIDE

So all the major features have landed. The App Manager v2 is not enabled by default (bug 1007059), but we should start thinking about the documentation. A major rewrite is needed as the whole UI has changed. How do we get there?

Unless Chris really wants to take this, I'm happy to.

(In reply to Will Bamberg [:wbamberg] from comment #4) > Unless Chris really wants to take this, I'm happy to. I'd enjoy writing this, but I'm totally slammed with other things at the moment. If you have a few free cycles Will, then go for it. (more gentlemanly conduct ensues...)

So I think maybe we need: * a rewrite of https://developer.mozilla.org/en-US/Firefox_OS/Using_the_App_Manager, probably in a separate parallel page for as long as the old stuff is relevant to some people, like what we've done with the Simulator. This version works with FxOS 1.2, yes? So everyone using the current app manager can switch as soon as this is available in Firefox? * a screencast with audio. I'm happy to have a go at this unless someone else wants to (Paul?). But I do think audio is important. Anything else? When do you need this? Firefox 33 entering Aurora?

(In reply to Will Bamberg [:wbamberg] from comment #6) > So I think maybe we need: > > * a rewrite of > https://developer.mozilla.org/en-US/Firefox_OS/Using_the_App_Manager, > probably in a separate parallel page for as long as the old stuff is > relevant to some people, like what we've done with the Simulator. This > version works with FxOS 1.2, yes? So everyone using the current app manager > can switch as soon as this is available in Firefox? Yes. But the new app manager (which just has been renamed to "WebIDE") is still preffed off, until bug 1007059. > * a screencast with audio. I'm happy to have a go at this unless someone > else wants to (Paul?). But I do think audio is important. I'm not very good at this. And my french accent won't help. I made a screencast here: http://people.mozilla.org/~prouget/webide2.mp4 but it only show the very basics. > Anything else? > > When do you need this? Firefox 33 entering Aurora? We need to documentation to be ready for Firefox 33 if possible (we're announcing this tool today, but it won't be available by default before a couple of weeks I guess). But let's not replace the current documentation until it's preffed on.

I've drafted a page on the WebIDE: https://developer.mozilla.org/en-US/docs/Tools/WebIDE. I'm not sure it's ready for an actual review (but if you think it is, please feel free :). A few things: * I've got instructions for upgrading your Firefox OS if you have a Geeksphone. What if people don't have Geeksphones? Do you know if we have a story for this? * the troubleshooting section is a bit thin. The section from the old app manager was quite repetitive, and lots of it was long the lines of "follow the instructions we already gave you". Are there any other good tips? * I still need to figure out where to put this stuff: https://developer.mozilla.org/en-US/Firefox_OS/Running_custom_builds_in_the_App_Manager * the section on custom runtimes is a bit thin. I need to understand that story a bit better I think. If I can, I'll work on a screencast next week.

Comment on attachment 8447576 [details] mdn.html Ryan, if you have some time to look at this, that'd be very helpful.

(In reply to Will Bamberg [:wbamberg] from comment #8) > Created attachment 8447576 [details] > mdn.html > > I've drafted a page on the WebIDE: > https://developer.mozilla.org/en-US/docs/Tools/WebIDE. I'm not sure it's > ready for an actual review (but if you think it is, please feel free :). Overall, I think it's great! :D In the "Editing Apps" section, it might be good to highlight the "manifest.webapp" file briefly, since that's what controls the app name, etc. There are many other pages that go into specifics, so nothing too long (assuming it makes sense to add). > A few things: > > * I've got instructions for upgrading your Firefox OS if you have a > Geeksphone. What if people don't have Geeksphones? Do you know if we have a > story for this? I think it's better to point to the general developer phone page[1], which also lists other devices, like the Flame, and each device page has info about updating it, if it's available at least. The story is still pretty poor across all available devices, but it is not really under our team's control. > * the troubleshooting section is a bit thin. The section from the old app > manager was quite repetitive, and lots of it was long the lines of "follow > the instructions we already gave you". Are there any other good tips? The current step 3 "edit asb_usb.ini" is Windows only. Maybe it belongs as a final hint in the Windows only section of setup before connecting. Maybe we can think of nice way to say "Are you sure you really did all the setup steps?" :) I know it's a bit condescending, but... many times people stop by #devtools and we discover they've just skipped something, so it's probably good to reinforce. If they've never seen this page before, I usually paste a link to the steps as first set of things to try. (Obviously a "real" solution would be for there to just be less steps... :) One day!) One difference from App Manager is that WebIDE will auto-install the ADB Helper add-on the first time you open WebIDE. However, if the user disables or removes it later, then no USB devices will be detected. So, it may be good to mention how to reinstall (from the same pane that lists the simulators) in case they have removed it for some reason. > * I still need to figure out where to put this stuff: > https://developer.mozilla.org/en-US/Firefox_OS/ > Running_custom_builds_in_the_App_Manager I don't believe this is worth including. This is a very advanced feature, and mostly only of use to Gaia developers. Even then, I do not believe too many make use of it. After this feature was added, it became possible to create custom simulators through Try builds, which makes this even less useful. (I added a note about the Try builds to that page.) Some people may still use this workflow, but I don't see a reason to mention on the WebIDE page. > * the section on custom runtimes is a bit thin. I need to understand that > story a bit better I think. Your current description is pretty good, but I'll try to provide more info. Some advanced users may be familiar with using ADB to control a device outside of WebIDE on the terminal to pull logs or other things. The ADB Helper add-on can sometimes conflict with other ADB usages outside of the WebIDE, so in that case advanced users might choose disable the ADB Helper addon and instead manually run an ADB forward command to connect their FxOS device. Then, they can connect WebIDE by using the Custom runtime option to enter the host and port that they setup during the port forwarding step. This allows using WebIDE and other ADB actions without conflicts. It can also be used to connect to a Fennec device, as you mention. The ADB Helper add-on does not currently support Android devices w/ Fennec correctly, so this custom path is required for the moment. Additionally, connecting WebIDE to Fennec doesn't really do anything of use at the moment. App Manager lets you connect to Fennec browser tabs, but this has not yet been ported to WebIDE (bug 1009604). I have also used this mode to test new connection mechanisms, so it can be nice to have for other purposes too. > If I can, I'll work on a screencast next week. Sounds great! [1]: https://developer.mozilla.org/en-US/Firefox_OS/Developer_phone_guide

Thanks for your comments, I've updated the doc. Screencast: https://dl.dropboxusercontent.com/u/91815060/webide.mp4 Let me know if it's OK (both whether, in general, it's a good script and whether this particular recording is good enough :). It's possible that I won't get much time to work on it before the Aurora release though.

(In reply to Will Bamberg [:wbamberg] from comment #11) > Thanks for your comments, I've updated the doc. It might be good to lift up the info about the additional runtime actions after connecting (runtime info, permissions, screenshot) into their own section? Right now it's kind of buried in "Running and Debugging Apps", and yet it's not directly related to that task. These features are pretty handy I think, but the UI makes them pretty hard to discover at the moment. (I just filed bug 1037115 to try for better discovery of the features.) > Screencast: https://dl.dropboxusercontent.com/u/91815060/webide.mp4 > > Let me know if it's OK (both whether, in general, it's a good script and > whether this particular recording is good enough :). It's possible that I > won't get much time to work on it before the Aurora release though. Screencast seems good to me! Seems to cover the major functions, and it seems like a clear recording. We should get a fun DevTools logo we can flash in at the beginning of these videos! ;)

(In reply to J. Ryan Stinnett [:jryans] from comment #12) > (In reply to Will Bamberg [:wbamberg] from comment #11) > > Thanks for your comments, I've updated the doc. > > It might be good to lift up the info about the additional runtime actions > after connecting (runtime info, permissions, screenshot) into their own > section? Right now it's kind of buried in "Running and Debugging Apps", and > yet it's not directly related to that task. > > These features are pretty handy I think, but the UI makes them pretty hard > to discover at the moment. (I just filed bug 1037115 to try for better > discovery of the features.) > > > Screencast: https://dl.dropboxusercontent.com/u/91815060/webide.mp4 > > > > Let me know if it's OK (both whether, in general, it's a good script and > > whether this particular recording is good enough :). It's possible that I > > won't get much time to work on it before the Aurora release though. > > Screencast seems good to me! Seems to cover the major functions, and it > seems like a clear recording. > > We should get a fun DevTools logo we can flash in at the beginning of these > videos! ;) There's an "unofficial", but very nice, one that I use for some other DevTools videos, like this: https://www.youtube.com/watch?v=sK8KU8oiF8s. The apps one seemed better for this particular tool, but it's easy to change. If we want an "official" DevTools logo, we can file a bug with Creative.

(In reply to Will Bamberg [:wbamberg] from comment #13) > If we want an "official" DevTools logo, we can file a bug with Creative. I don't have the bub number in mind, but there's already one.

(the screencast is awesome!)

Thanks paul and jryans. There were a couple of things that bothered me, so I made a new recording, uploaded it to https://www.youtube.com/watch?v=2xmj4W8O3E4, and embedded it in https://developer.mozilla.org/en-US/docs/Tools/WebIDE. The screencast doesn't mention to webide.enabled pref, as I'm not sure whether that will still be true when it enters Aurora.

Will, this is excellent. A couple of comments: Webide is still preffed off, and I'm not sure when it will change. We're working on that. > System requirements You might want to add a link to the "Connecting_a_Firefox_OS_device" sub section as drivers and udev configuration might be required. > enable remote debugging There are 2 different ways to enable the devtools. One for 1.3, and one for 1.3+. You might want to mention that here. > Troubleshooting This is a critical part of the documentation. Don't you think we should add all the items from https://developer.mozilla.org/en-US/Firefox_OS/Using_the_App_Manager#Troubleshooting ? > Adding a Simulator Up to you, but you might want to mention that there's no need to keep the "Extra Component" page open. The simulator is installed in the background and will show up in the menu as soon as it's installed. But Firefox needs to stay open. > Create a new app Don't mention the word "mortar". There's no point of confusing the user with yet-another random name. > Running and debugging apps Please mention that any edited file needs to be saved first (there's a star next to the file name in the tree) And one more thing: can you say a word about the "remove" button in the app summary panel? People tend to miss it (how to remove a project?).

Comment on attachment 8447576 [details] mdn.html The only thing I think that could be a blocker is the troubleshooting section. See above comment.

Thanks Paul, these are useful comments. > > Troubleshooting > > This is a critical part of the documentation. Don't you think we should add > all the items from > https://developer.mozilla.org/en-US/Firefox_OS/ > Using_the_App_Manager#Troubleshooting ? > It is important, but unfortunately the Troubleshooting section in the app manager documentation is confusing. It's almost, but not quite, a repetition of steps already listed in the "Device and system configuration" section (https://developer.mozilla.org/en-US/Firefox_OS/Using_the_App_Manager#Device_and_system_configuration), but with slightly different wording. So there are 2 slightly different checklists, meaning that someone trying to get it to work needs to refer to both places and work out when an item worded differently in each list is actually the same item. Also, when someone finds a new item to add, it's not obvious which list they should add it to, so the lists will diverge for no good reason. So I deliberately didn't copy this approach. What I've done is: * amalgamated those 2 lists into one list here: https://developer.mozilla.org/en-US/docs/Tools/WebIDE#Connecting_a_Firefox_OS_device * added a single troubleshooting item that directs people at this list and asks them to double check. To go through the old Troubleshooting section a step at a time: > If clicking the button corresponding to your Firefox OS phone doesn't do anything, > make sure you haven't connected an Android phone at the same time as the Firefox OS phone to your computer. I've covered this in https://developer.mozilla.org/en-US/docs/Tools/WebIDE#Connecting_a_Firefox_OS_device > Read the Device and system configuration section thoroughly, and make sure all the steps are followed: I've kept this in the Troubleshooting section, pointing people at the main list in https://developer.mozilla.org/en-US/docs/Tools/WebIDE#Connecting_a_Firefox_OS_device. > Is your device running at least Firefox OS 1.2? Covered in https://developer.mozilla.org/en-US/docs/Tools/WebIDE#Connecting_a_Firefox_OS_device. > Don't see all the apps? Do you need to enable Certified Apps debugging? This wasn't covered in https://developer.mozilla.org/en-US/docs/Tools/WebIDE#Connecting_a_Firefox_OS_device, and I think perhaps should be. > Did you enable "Remote Debugging" in the settings of your phone? Covered in https://developer.mozilla.org/en-US/docs/Tools/WebIDE#Connecting_a_Firefox_OS_device. > If you are not using the ADB Helper add-on: > Did you successfully run the adb forward command? Covered under Custom runtimes, but this is treated as an edge case: the main thread of the documentation assumes you're using ADB Helper. > If you are using the ADB Helper add-on and your device is not listed in the bottom toolbar: > If you use Linux, make sure to setup udev correctly > If you use Windows, make sure to install the appropriate drivers This is all covered in https://developer.mozilla.org/en-US/docs/Tools/WebIDE#Connecting_a_Firefox_OS_device > You can also enable verbose logging to gather diagnostics: I've kept this in Troubleshooting. > See "???????" instead of the device name on Linux? You have permissions issues. Make sure to setup udev correctly. Linux udev is in https://developer.mozilla.org/en-US/docs/Tools/WebIDE#Connecting_a_Firefox_OS_device. Maybe it's worth mentioning this specific error condition? I'm not sure. > Is your phone screen unlocked? Covered in https://developer.mozilla.org/en-US/docs/Tools/WebIDE#Connecting_a_Firefox_OS_device > If the command "adb devices" shows no entries even though the phone is connected and unlocked, you may have to edit adb_usb.ini. Covered in https://developer.mozilla.org/en-US/docs/Tools/WebIDE#Connecting_a_Firefox_OS_device

Thanks Paul. (In reply to Paul Rouget [:paul] (slow to respond. Ping me on IRC) from comment #17) > > > System requirements > > You might want to add a link to the "Connecting_a_Firefox_OS_device" sub > section as drivers and udev configuration might be required. I didn't include this because I think of "System Requirements" as the baseline you need to get anything off the ground, and this is a specific bit of extra setup you might need. But I can add it if you feel strongly. > > > enable remote debugging > > There are 2 different ways to enable the devtools. One for 1.3, and one for > 1.3+. You might want to mention that here. You mean 1.4+? I did cover those 2 different ways, but didn't mention the correlation with Firefox OS versions, and I've added that. > > > Troubleshooting > > This is a critical part of the documentation. Don't you think we should add > all the items from > https://developer.mozilla.org/en-US/Firefox_OS/ > Using_the_App_Manager#Troubleshooting ? See comment 19 above for that. > > > Adding a Simulator > > Up to you, but you might want to mention that there's no need to keep the > "Extra Component" page open. The simulator is installed in the background > and will show up in the menu as soon as it's installed. But Firefox needs to > stay open. > > > Create a new app > > Don't mention the word "mortar". There's no point of confusing the user with > yet-another random name. > Do you think I should mention and link to the template collection, just not by the name Mortar? I think it's helpful. > > Running and debugging apps > > Please mention that any edited file needs to be saved first (there's a star > next to the file name in the tree) > Done. > And one more thing: > > can you say a word about the "remove" button in the app summary panel? > People tend to miss it (how to remove a project?). Done, and good point, it took me a little while to find that.

> Do you think I should mention and link to the template collection, just not by the name Mortar? I think it's helpful. We don't know yet how our templating mechanism will evolve. So keep it simple for the moment (no link, no mention). > > Troubleshooting > So I deliberately didn't copy this approach. So I understand what you're saying, but we need a one single section about troubleshooting as WebIDE has a "troubleshooting" button when an error occurs, and it opens a MDN link. Also, FYI, we added a new screen: Project > Preferences, where you can configure some WebIDE options. Thanks for addressing all the other comments.

> We don't know yet how our templating mechanism will evolve. So keep it > simple for the moment (no link, no mention). (no link, no mention to "mortar")*

(In reply to Paul Rouget [:paul] (slow to respond. Ping me on IRC) from comment #21) > > Do you think I should mention and link to the template collection, just not by the name Mortar? I think it's helpful. > > We don't know yet how our templating mechanism will evolve. So keep it > simple for the moment (no link, no mention). > > > > Troubleshooting > > So I deliberately didn't copy this approach. > > So I understand what you're saying, but we need a one single section about > troubleshooting as WebIDE has a "troubleshooting" button when an error > occurs, and it opens a MDN link. > OK, so the problem is that the Troubleshooting section I have here: https://developer.mozilla.org/en-US/docs/Tools/WebIDE#Troubleshooting is specific to connecting a device, rather than top-level for WebIDE? So would it work for you if I basically moved https://developer.mozilla.org/en-US/docs/Tools/WebIDE#Troubleshooting to the top level, and changed the wording to be more generic, but still directed people to the one checklist in https://developer.mozilla.org/en-US/docs/Tools/WebIDE#Connecting_a_Firefox_OS_device? Or is it critical to duplicate the checklist too? > Also, FYI, we added a new screen: Project > Preferences, where you can > configure some WebIDE options. > > Thanks for addressing all the other comments.

I think an exhaustive list would be best, without multiple links in it. It will duplicate information. But I think it's ok (even if a little harder to maintain). It is very critical that this list is exhaustive, but still stays clear and concise. Maybe you want to create an different page for that. We redirected many people to https://developer.mozilla.org/en-US/Firefox_OS/Using_the_App_Manager#Troubleshooting - and it usually works well. I would even go as far as I saying that this troubleshooting section is more important than the main documentation page (many people never read the app manager doc).

Then I think this works better as a separate page. I've created a new page "Troubleshooting": https://developer.mozilla.org/en-US/docs/Tools/WebIDE/Troubleshooting and linked to it from the main page in a couple of places.

The troubleshooting page is great. We might need to update the screenshots: we added a preference panel (In the project menu), and the design of the menus have changed a bit. Will, can we consider this done?

Oh, and for "Debugging certified apps", we just landed a patch that adds a button in "Runtime info" that does that for you.

Updated the doc. Let's consider this bug fixed. Thanks a lot Will.