1078742 - Add a Manifest Editor to WebIDE

Status: RESOLVED WONTFIX

(DevTools Graveyard :: WebIDE, defect)

Description

[Christopher Van Wiemeersch [:cvan]]

Maybe this is something that is already in the WebIDE, but I couldn't find it. So feel free to ignore all of this in that case.

I know bug 921254 was filed for a JSON editor for manifests. I'm unclear of bug 921254 comment 2, so I decided to file this bug. But if it's invalid or not something you guys want to do, feel free to mark it as such or WONTFIX. I do genuinely think it's helpful for a lot of devs (not just the beginners but advanced devs too who don't want to keep manually writing JSON).

A manifest builder (wizard) would be even cooler. This way developers don't have to manually write JSON from scratch.

I've built a few prototypes of manifest builders and editors. I won't distract you with all of those, but there's one idea in particular I like: inline validation of manifest. See my sketch on the left side here:

    http://people.mozilla.org/~cwiemeersch/manifest/seamission-sketches/Pages/2.html

JSON validation (something like http://jsonlint.org/ or http://jsoneditoronline.org/, which was discussed in bug 921254) could show manifest errors or helpful notices as the developer creates or edits a manifest.

Today, developers have to go from App Manager/WebIDE -> Editor -> MDN -> Editor -> Save changes -> App Manager/WebIDE to check validity. Or in the worst cases, developers are having to re-zip their packaged apps or reupload their hosted-app manifests to address a validation issue in the Marketplace submission flow (or when updating the manifest for an existing submitted hosted app or submitting a new version of a packaged app). It's really quite a tedious and frustrating process.

The Marketplace UX team (specifically, Elizabeth Hunt and Bram Pitoyo) are working on integrating a Manifest Builder to the Marketplace. If the WebIDE folks decide they do want to add a JSON editor or manifest wizard/editor, it's probably worth discussing with them. Their prototypes area available for viewing here: http://62shu8.axshare.com/

As I see it there should be two goals:

* Help developers so they don't have to write JSON from scratch
* Help developers address validation issues in one spot, so they don't have to keep toggling windows and get frustrated

Hopefully, the WebIDE can fix these. I think it will really delight developers and avoid lots of existing friction and frustration.

Comment 1

[Christopher Van Wiemeersch [:cvan]]

Ah, I just found this one-click "New App" flow:

https://www.dropbox.com/s/4p7dpwdeuhjttru/Screenshot%202014-10-06%2014.39.55.png?dl=0

Quite nice!

Comment 2

[Paul Rouget [:paul]]

The original approach was not quite right I think (the manifest editor in app manager). It's in between a rich editor and a plain text editor. Building a wizard or a rich UI as seen here: http://62shu8.axshare.com/#p=manifest_builder sounds like a better idea.

We could switch from rich to plaint text mode.

jryan, sole, jen, I let you guys decide.

Comment 3

[Elizabeth Hunt[:ezoehunt]]

In Marketplace-land, we'll be including the ability to upload an existing manifest into the Manifest Builder. So you could add/edit it and then download the new generated manifest.

We're aiming to get the Manifest Builder underway as soon as possible. When we've finalized the UX (hoping this week), we'll reach out to the WebIDE folks. As a group, think we'll be able to figure out a workflow that makes sense for WebIDE.

Comment 4

[Soledad Penades [:sole] [:spenades]]

From what I can remember, the former manifest editor in App Manager was dropped because it was full of edge cases and was very difficult to maintain.

The idea was to just drop to a "JSON editor", and progressively refine it:

1) adding validation using the famous new validator in JS that Jen worked on

2) maybe add another editor view of the manifest which would let you edit field by field without fear of breaking the JSON file, and would also have some help explaining what each field/section was. A bit like that wizard in http://62shu8.axshare.com/#p=manifest_builder but probably more like Android's graphical manifest editor: https://lh3.googleusercontent.com/hEIwqe0WSBzDmwlM-qV5c3aBPsek4GQyCNoHt0h1IYCNAUl0nFJjK6-GUSkDrNGUAO-Xb-gDkcZmixFSK5-yA5_I-sRtqIkmoIlUhNcTjUQ2TqfVhQ - note I'm not saying this is perfect, it was a bit atrocious to use and I personally always ended up using the text editor, but I'm me and you're not me.

3) so maybe step 3 is having a built-in manifest builder--but perhaps it should be turned into more like an "app wizard" since it will set up more than just a manifest; the manifest is just one artifact that needs to exist for the app to work

Once you get 1 and 2 anything created with 3 should be editable and instantly locally validated without having to contact marketplace's validation services--this is why we need that JS validator.

Comment 5

[J. Ryan Stinnett [:jryans] (Use needinfo, replies may be slow)]

(In reply to Elizabeth Hunt from comment #3)
> In Marketplace-land, we'll be including the ability to upload an existing
> manifest into the Manifest Builder. So you could add/edit it and then
> download the new generated manifest.
> 
> We're aiming to get the Manifest Builder underway as soon as possible. When
> we've finalized the UX (hoping this week), we'll reach out to the WebIDE
> folks. As a group, think we'll be able to figure out a workflow that makes
> sense for WebIDE.

Will Marketplace's Manifest Builder require being logged into the Marketplace to use?

Down the road, it might be neat to include the Marketplace Manifest Builder via an iframe into WebIDE so we don't duplicate work.  So, assuming your implementation does not require being logged in (it would seem that way if you can upload and work from a random manifest), then this might be possible.

Comment 6

[J. Ryan Stinnett [:jryans] (Use needinfo, replies may be slow)]

Sole's plan of progressive refinement makes sense to me: validation, then separate editor view, then a full wizard.

Comment 7

[Christopher Van Wiemeersch [:cvan]]

(In reply to J. Ryan Stinnett [:jryans] from comment #5)
> Will Marketplace's Manifest Builder require being logged into the
> Marketplace to use?

Anonymous users should be able to use it as well, à la the existing Manifest Validators:

    https://marketplace.firefox.com/developers/validator

> Down the road, it might be neat to include the Marketplace Manifest Builder
> via an iframe into WebIDE so we don't duplicate work.  So, assuming your
> implementation does not require being logged in (it would seem that way if
> you can upload and work from a random manifest), then this might be possible.

That sounds splendid and, I agree, would keep things DRY - assuming the integration is smooth and there are no issues with that on the Firefox side of things (I have no idea how that works TBH).

Comment 8

[Jen Fong-Adwent [:ednapiranha]]

An app wizard is a good and safe way to avoid new users from making up weird errors, but as they become more familiar they will likely just edit the text file directly.

I am also curious as to what level of complexity most developers encounter when creating the manifest. Is there a common list of questions they ask about the manifest file? Or are most manifests pretty straightforward?

As an aside, I think the real question is what are the situations where people are having trouble with the manifest and what parts of the existing docs confuse users from understanding its purpose, and why this results in having to build the wizard. It might be good to combine both the direction of the wizard's design along with improving existing documentation so they can go hand in hand - my concern is that we rely on one more than the other, etc.

Comment 9

[Elizabeth Hunt[:ezoehunt]]

You will be able to use the Manifest Builder if you are not logged in. This should make it easier to integrate into WebIDE in the future.

We did some research a few months ago to learn how app developers create the manifest file and their understanding of the various fields. The primary learning is that tools and documentation need to provide opinionated direction and/or suggestions so that developers can "skip" things that are not relevant to their apps.

The MDN team has already updated the documentation based on our findings. And we'll continue to refine the documentation as we create the Manifest Builder. 

Additionally our group of "Manifest Experts" have determined that several manifest fields are relevant only to small percent of sophisticated developers. So the Manifest Builder (and future documentation) will present the most commonly-used manifest fields first, followed by fields you might need in X (or recommended) circumstances.

Basically we want to provide more guidance so that developers correctly complete the fields relevant to their apps, without getting bogged down in fields that aren't relevant to them.

Comment 10

[J. Ryan Stinnett [:jryans] (Use needinfo, replies may be slow)]

WebIDE is slated for removal (bug 1314811), so there are no plans to add to the current set of features.