807107 - Create a template for displaying Reference Apps

Status: RESOLVED FIXED

(Marketplace Graveyard :: Developer Pages, defect)

Description

[Daniel Buchner [:dbuc]]

Attachment: Reference App template functional mockup

Included is a mock-up for this template.

Comment 1

[Bram Pitoyo [:bram]]

This is a good mockup. Providing links to view code, markup and website of 3rd-party libraries is a good call. I might have refinements to make, but minor ones.

Could you share the file you used to create this mockup?

How many reference apps are we planning to create? I know that three already exists. I imagine that some apps will have more screenshots, longer names, or more libraries used than others, so I want to make sure that the template will be able to handle anything we throw at it.

Lastly, this template will also need to have the link to reference articles on the bottom of it. This is pretty easy to design for.

Comment 2

[Daniel Buchner [:dbuc]]

Attachment: PSD for Reference App page template

Comment 3

[Fred Wenzel [:wenzel]]

I like it. What are the next steps here?

Some feedback/questions for the mockup:
- should we have a way for the developers to weigh in? Over in bug 804820 tofumatt linked to an example of what this could look like. If this is too wordy, we could also put that content into the README.md file on github and link to it.
- the CTA is "download source" -- do we really mean that, or do we want to link to the project's github page instead, allowing people to read the source? Or do we want both?
- depending on what web apis we use, (i.e., if this runs on desktop), I think a live demo would be really cool. Is this something we should pursue, or keep it at screen shots for now?

Comment 4

[Daniel Buchner [:dbuc]]

Next Steps:

1. create reference apps
2. start on template - all apps should live on Github and data should be pulled from there via API

Feedback responses:

1. This is a great idea, and we should add a UI element at the bottom of the Description section that reveals this in-depth developer/creator overview, I can add this to the specs/mock
2. We could change this to View on Github and let them download or fork it there. Perhaps we should add an installation/simulation button too?
3. If we up-leveled live examples of API usage, what happens if the example is reliant on an API not accessible on whatever platform the developer is on? (Desktop/Android/Firefox OS)

Comment 5

[Bram Pitoyo [:bram]]

A little additional note on this bug: I will try to follow this layout when designing the app generator (bug 796036), so our pages look and feel integrated.

Comment 6

[Fred Wenzel [:wenzel]]

San, please finalize the template mock based on comment 4 this week. Thanks!

Comment 7

[Fred Wenzel [:wenzel]]

(In reply to Fred Wenzel [:wenzel] from comment #6)
> San, please finalize the template mock based on comment 4 this week. Thanks!

and by "San", I mean Dan. lol

Comment 8

[Daniel Buchner [:dbuc]]

Attachment: final Reference App Template design

Added link for viewing full developer walk-through (this will lead to a separate page on DevHub)

Comment 9

[Fred Wenzel [:wenzel]]

This looks good to me.

Bram: Will you look it over and voice any final concerns? If there are none, we can close this and move over to implementation (and the first reference apps!) in the next milestone.

Comment 10

[Bram Pitoyo [:bram]]

My only two concerns are minor ones, and apply to every page that we create, site-wide:

1. Make sure that we use the existing p, h3 and h2 font sizes to make this page consistent with the rest of DevHub. Don’t invent new font-size.

2. Make sure that we only use icon when it provides additional information that the user find useful. Icon is also great to use if we use the same graphic elsewhere in the documentation. For example, in MDN and on third-party sites we linked to. Without context or usefulness, icons have a danger of being frivolous and purely decorative at worst, and increase page loading time at best.

These are about it, and we’re good to go!

Comment 11

[Fred Wenzel [:wenzel]]

All right thanks! This is good to go, will ask further questions if they come up in the implementation phase.

Comment 12

[Jen Fong-Adwent [:ednapiranha]]

(In reply to Bram Pitoyo [:bram] from comment #10)
> My only two concerns are minor ones, and apply to every page that we create,
> site-wide:
> 
> 1. Make sure that we use the existing p, h3 and h2 font sizes to make this
> page consistent with the rest of DevHub. Don’t invent new font-size.
> 
> 2. Make sure that we only use icon when it provides additional information
> that the user find useful. Icon is also great to use if we use the same
> graphic elsewhere in the documentation. For example, in MDN and on
> third-party sites we linked to. Without context or usefulness, icons have a
> danger of being frivolous and purely decorative at worst, and increase page
> loading time at best.
> 
> These are about it, and we’re good to go!

Hey Bram, I agree with your points too - noticed a couple of things during implementation and wanted to see what you all thought:

1. For the Web APIs, Custom elements and Third party libraries, would it make sense to just link the title of the library to the source instead of adding a 'view code' beside? Reduces clutter in the page.

2. I agree, the icons for those libraries are not really useful for anything in terms of getting to the information.

Let me know what you think.

Comment 13

[Bram Pitoyo [:bram]]

(In reply to Jen Fong-Adwent [:ednapiranha] from comment #12)
> 1. For the Web APIs, Custom elements and Third party libraries, would it
> make sense to just link the title of the library to the source instead of
> adding a 'view code' beside? Reduces clutter in the page.

Yes. Please link the title directly to the source. No need for “view code”.


> 2. I agree, the icons for those libraries are not really useful for anything
> in terms of getting to the information.

In MDN, do we use icons to communicate Web API, Custom Element and Libraries? If yes, then maybe there is an argument to mirror the icons here for visual continuity. Otherwise, no icon is needed.

Comment 14

[Jen Fong-Adwent [:ednapiranha]]

Bram(In reply to Bram Pitoyo [:bram] from comment #13)
> (In reply to Jen Fong-Adwent [:ednapiranha] from comment #12)
> > 1. For the Web APIs, Custom elements and Third party libraries, would it
> > make sense to just link the title of the library to the source instead of
> > adding a 'view code' beside? Reduces clutter in the page.
> 
> Yes. Please link the title directly to the source. No need for “view code”.
> 
> 
> > 2. I agree, the icons for those libraries are not really useful for anything
> > in terms of getting to the information.
> 
> In MDN, do we use icons to communicate Web API, Custom Element and
> Libraries? If yes, then maybe there is an argument to mirror the icons here
> for visual continuity. Otherwise, no icon is needed.

I don't think I see any icons for the Web API or Custom Elements. Libraries outside of these two are third party ones, such as nodejs, etc. which can be fine as regular links. So I'll leave it as links for all to keep consistency - we can change later if necessary.