Re: Rewrite of App Centre "Quickstart" section

[Chris Mills]

Thanks for the suggestions Richard. I didn’t put stuff like this in originally as I thought it would be too obvious for many of the MDN readers, who are generally expected to be experienced web developers.

But you never know - for this kind of complete beginner’s article, it may well attract a wider audience.

Chris Mills
Senior tech writer || Mozilla
developer.mozilla.org || MDN
cmi...@mozilla.com || @chrisdavidmills



On 1 Apr 2014, at 23:55, m...@sherpa.co.nz wrote:

> Hi,
>
> I've made a couple of suggestions in the etherpad - a section to describe
> what the reader should know (e.g. web basics e.g. not too much) and a
> section on the tools needed - so they can get setup before starting and can
> follow the guide without being interrupted by finding or installing tools.
>
> I also wonder if the last section (see also/further reading) would be better
> titled 'Learn more'? Depending on your view of the 'should know' section
> might we also include a link to a resource(s) on learning
> HTML/CSS/JavaScript?
>
> Hope these help
>
> Regards
> Richard Bloor
>
> mobile: +64 21 650 784
> skype: richard_bloor
> timezone: NZDT
>
>
> ----------------------------------------------------------------------------
> -
> Date: Tue, 1 Apr 2014 14:22:51 +0100
> From: Chris Mills <cmi...@mozilla.com>
> To: dev-mdc <dev...@lists.mozilla.org>, engagement Engaged
> <engag...@mozilla.com>
> Subject: Rewrite of App Centre "Quickstart" section
> Message-ID: <E341E6C5-6D3F-49ED...@mozilla.com>
> Content-Type: text/plain; charset=windows-1252
>
> Hi all,
>
> Regarding
>
> https://developer.mozilla.org/en-US/Apps/Quickstart
>
> We have a problem - it isn?t really a quickstart; it is 10 documents in all,
> most of which deal with a different part of the apps problem in brief. What
> we really need is a single document to get people up to speed quickl,y which
> then points to other parts of the app center for more details.
>
> I have written a plan for this - including restructured content (which still
> needs some work) - at
>
> https://etherpad.mozilla.org/apps-quickstart-rewrite
>
> Do we think this sounds like the single page of content we need for a
> quickstart guide on creating installable apps?
>
> Feedback welcome; i?ll start implementing this in a week perhaps, once
> everyone has had a chance to feed back.
>
> Remember that the content needs some work; it is mainly the structure I am
> interested in getting feedback on here.
>
> thanks!
>
> Chris Mills
> Senior tech writer || Mozilla
> developer.mozilla.org || MDN
> cmi...@mozilla.com || @chrisdavidmills
>
> _______________________________________________
> dev-mdc mailing list
> dev...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-mdc

[Francesco Iovine]

Hi Chris,

I agree that the "Quickstart" section needs to be restructured: after the
Work Weekend I had the chance to think a bit more about it.

My idea of quickstart is something similar to the quickstart of Polymer [1]
for example:

start ---> getting the code ---> using elements ---> creating elements --->
the platform ---> API reference


I'm referring mainly to the "next steps" section that they put at the
bottom of the page.

For the quickstart of the App Center, steps would be the following:

Introduction ---> Firefox OS ---> Skills needed ---> Get the Tools --->
Your first app ----> Quickstart template ----> Adding a manifest -----> Web
API functionality ----> Install API -----> API permissions ----> Testing
your app -----> App Submission and distribution -----> Learn More


Do you think readers would benefit of a step-by-step structure and a "next
steps" section at the end of each page? Or maybe this structure is
incoherent with the other sections in MDN?

Other important questions of developers approaching Open Web App
development are:

- Q: should I use a framework/library? A: it depends
- Q: what is the "right way" to write my code? A: no "right way", but
best practices
- Q: is there any example app I can start playing with?. A: yes!

So why not to insert FAQs here too? Answers to FAQs might link to articles
which examine in depth the topic. Does it make sense?

Hope it helps! :)

Best,

Francesco <https://developer.mozilla.org/en-US/profiles/franciov>

[1] http://www.polymer-project.org/


Francesco <http://www.francesco.iovine.name/>

[Chris Mills]

On 4 Apr 2014, at 12:33, Francesco Iovine <f.io...@gmail.com> wrote:

> Hi Chris,
>
> I agree that the "Quickstart" section needs to be restructured: after the Work Weekend I had the chance to think a bit more about it.
>
> My idea of quickstart is something similar to the quickstart of Polymer [1] for example:
>
> start ---> getting the code ---> using elements ---> creating elements ---> the platform ---> API reference
>
> I'm referring mainly to the "next steps" section that they put at the bottom of the page.
>
> For the quickstart of the App Center, steps would be the following:
>
> Introduction ---> Firefox OS ---> Skills needed ---> Get the Tools ---> Your first app ----> Quickstart template ----> Adding a manifest -----> Web API functionality ----> Install API -----> API permissions ----> Testing your app -----> App Submission and distribution -----> Learn More
>
> Do you think readers would benefit of a step-by-step structure and a "next steps" section at the end of each page? Or maybe this structure is incoherent with the other sections in MDN?

A step-by-step approach is what I was hoping to write for this document - do you not think it does that ok?

>
> Other important questions of developers approaching Open Web App development are:

> • Q: should I use a framework/library? A: it depends
> • Q: what is the "right way" to write my code? A: no "right way", but best practices
> • Q: is there any example app I can start playing with?. A: yes!

> So why not to insert FAQs here too? Answers to FAQs might link to articles which examine in depth the topic. Does it make sense?

A basic level set of FAQs would be a good idea here too. I mean, we have an App Development FAQ:

https://developer.mozilla.org/en-US/Apps/Build/App_development_FAQ

But this is much more in depth, and assumes that you are already building your app but have questions about specific functionality. This FAQ would be much more beginner’s questions, like the ones you’ve suggested,

[Francesco Iovine]

On 7 April 2014 13:03, Chris Mills <cmi...@mozilla.com> wrote:

>
> On 4 Apr 2014, at 12:33, Francesco Iovine <f.io...@gmail.com> wrote:
>
> > Hi Chris,
> >
> > I agree that the "Quickstart" section needs to be restructured: after
> the Work Weekend I had the chance to think a bit more about it.
> >
> > My idea of quickstart is something similar to the quickstart of Polymer
> [1] for example:
> >
> > start ---> getting the code ---> using elements ---> creating elements
> ---> the platform ---> API reference
> >
> > I'm referring mainly to the "next steps" section that they put at the
> bottom of the page.
> >
> > For the quickstart of the App Center, steps would be the following:
> >
> > Introduction ---> Firefox OS ---> Skills needed ---> Get the Tools --->
> Your first app ----> Quickstart template ----> Adding a manifest -----> Web
> API functionality ----> Install API -----> API permissions ----> Testing
> your app -----> App Submission and distribution -----> Learn More
> >
> > Do you think readers would benefit of a step-by-step structure and a
> "next steps" section at the end of each page? Or maybe this structure is
> incoherent with the other sections in MDN?
>
> A step-by-step approach is what I was hoping to write for this document -
> do you not think it does that ok?
>

*Yes, definitely ;)*

>
> >
> > Other important questions of developers approaching Open Web App
> development are:

> > * Q: should I use a framework/library? A: it depends
> > * Q: what is the "right way" to write my code? A: no "right way",
> but best practices
> > * Q: is there any example app I can start playing with?. A: yes!

> > So why not to insert FAQs here too? Answers to FAQs might link to
> articles which examine in depth the topic. Does it make sense?
>
> A basic level set of FAQs would be a good idea here too. I mean, we have
> an App Development FAQ:
>
> https://developer.mozilla.org/en-US/Apps/Build/App_development_FAQ
>
> But this is much more in depth, and assumes that you are already building
> your app but have questions about specific functionality. This FAQ would be
> much more beginner's questions, like the ones you've suggested,

*Agree.*

[Chris Mills]

On 7 Apr 2014, at 12:16, Francesco Iovine <f.io...@gmail.com> wrote:

>
>
> On 7 April 2014 13:03, Chris Mills <cmi...@mozilla.com> wrote:
>
> On 4 Apr 2014, at 12:33, Francesco Iovine <f.io...@gmail.com> wrote:
>
> > Hi Chris,
> >
> > I agree that the "Quickstart" section needs to be restructured: after the Work Weekend I had the chance to think a bit more about it.
> >
> > My idea of quickstart is something similar to the quickstart of Polymer [1] for example:
> >
> > start ---> getting the code ---> using elements ---> creating elements ---> the platform ---> API reference
> >
> > I'm referring mainly to the "next steps" section that they put at the bottom of the page.
> >
> > For the quickstart of the App Center, steps would be the following:
> >
> > Introduction ---> Firefox OS ---> Skills needed ---> Get the Tools ---> Your first app ----> Quickstart template ----> Adding a manifest -----> Web API functionality ----> Install API -----> API permissions ----> Testing your app -----> App Submission and distribution -----> Learn More
> >
> > Do you think readers would benefit of a step-by-step structure and a "next steps" section at the end of each page? Or maybe this structure is incoherent with the other sections in MDN?
>
> A step-by-step approach is what I was hoping to write for this document - do you not think it does that ok?
>

> Yes, definitely ;)

>
>
> >
> > Other important questions of developers approaching Open Web App development are:

> > • Q: should I use a framework/library? A: it depends
> > • Q: what is the "right way" to write my code? A: no "right way", but best practices
> > • Q: is there any example app I can start playing with?. A: yes!

> > So why not to insert FAQs here too? Answers to FAQs might link to articles which examine in depth the topic. Does it make sense?
>
> A basic level set of FAQs would be a good idea here too. I mean, we have an App Development FAQ:
>
> https://developer.mozilla.org/en-US/Apps/Build/App_development_FAQ
>
> But this is much more in depth, and assumes that you are already building your app but have questions about specific functionality. This FAQ would be much more beginner’s questions, like the ones you’ve suggested,
>

> Agree.

Party on! I think I’ll start writing the finished version of the Quickstart, now I’ve got a few decent bits of feedback.

As always, feel free to keep pitching in ideas everyone ;-)

[Chris Mills]

The new Apps Quickstart page is now up:

https://developer.mozilla.org/en-US/Apps/Quickstart

Before I link this on the main App Center, does anyone have any concerns of comments about it? I’ve basically condensed the rather waffly 10 Quickstart pages we had before, into one more effectively, to-the-point article.

Chris Mills
Senior tech writer || Mozilla
developer.mozilla.org || MDN
cmi...@mozilla.com || @chrisdavidmills

On 1 Apr 2014, at 14:22, Chris Mills <cmi...@mozilla.com> wrote:

> Hi all,
>
> Regarding
>
> https://developer.mozilla.org/en-US/Apps/Quickstart
>

> We have a problem - it isn’t really a quickstart; it is 10 documents in all, most of which deal with a different part of the apps problem in brief. What we really need is a single document to get people up to speed quickl,y which then points to other parts of the app center for more details.

>
> I have written a plan for this - including restructured content (which still needs some work) - at
>
> https://etherpad.mozilla.org/apps-quickstart-rewrite
>
> Do we think this sounds like the single page of content we need for a quickstart guide on creating installable apps?
>

> Feedback welcome; i’ll start implementing this in a week perhaps, once everyone has had a chance to feed back.

[Francesco Iovine]

The Apps Quickstart page looks very good to me now, well done!

Just a little thing I noticed: the well commented one hundred lines of code
in "Our code for the quickstart example functionality" section might look
like something difficult for a newbie, but it's not! Maybe it might be
splitted in 3-4 parts or simplified? It's a quickstart after all.

Francesco <https://developer.mozilla.org/en-US/profiles/franciov>

[Chris Mills]

Good call Francesco. I’ve broken up the large code block into a few parts now.

On 14 Apr 2014, at 13:39, Francesco Iovine <f.io...@gmail.com> wrote:

> The Apps Quickstart page looks very good to me now, well done!
>
> Just a little thing I noticed: the well commented one hundred lines of code in "Our code for the quickstart example functionality" section might look like something difficult for a newbie, but it's not! Maybe it might be splitted in 3-4 parts or simplified? It's a quickstart after all.
>
> Francesco
>
>