Re: [b2g] The dev.moz.org docs
Thanks again for your input Adrian. I am not 100% sure I’ll get time to do this
before the Xmas vacation starts, but I’ll try. I agree that starting with a
site map/overview of the Firefox OS docs area is a good idea to start with.
I’ll create something asap and then we can start working out an improvement
plan.
Chris Mills
Senior tech writer || Mozilla
developer.mozilla.org || MDN
cmi...@mozilla.com || @chrisdavidmills
On 13 Dec 2013, at 15:54, Adrian Custer wrote:
> On 12/13/13, 1:00 PM, Chris Mills wrote:
>>
>> On 13 Dec 2013, at 14:51, Adrian Custer wrote:
>>> You are lost in a maze of twisty pages, all alike…
>>
>> This is definitely a thing I need to work on. There is a lot here,
>> and it could use some improved IA. I kind of got to the point where I
>> couldn’t see the wood for the trees with this section of the site, so
>> I left it for a while and went on to other things. Again, any ideas
>> will be listened to ;-)
>
>
> Do you have a higher level overview of the docs? The current organization
> seems kind of strange. When I was writing the Gnumeric Manual, I needed a
> clear outline just to keep my own mind clear of what goes where. We surely
> need something similar to all be on the same page when working
> collaboratively on a wiki.
>
>
> The current layout lacks a coherent logic. Working from the left-hand menu on:
> https://developer.mozilla.org/en-US/Firefox_OS
> (Note that right clicking on each top level element opens an extra page for
> that top level element.)
>
>
> Introduction:
> => Is this focused at everyone or just developers? A key question is
> who is tragetted by these docs and how can we redirect the other
> readers quickly to other docs.
> => Needs a clear purpose (ie. Hardware requirements is strange to find
> here.)
>
> Usage Tips:
> => These are tips for developers, i.e. not 'usage'
>
> Platform Guide:
> => Needs to start with a simple archi diagram:
>[ Gaia Web Apps ] [ Other Web Apps]
>[ Gecko ]
>[Gonk: kernel, drivers, libs ]
> => Needs to work systematically through the layers:
> * Kernel
> * Drivers and libs
> = Gonk
> * Gecko
> * Web App Security Control
> * Web App APIs
> = 'Gecko'?
> * Common libraries for Web Apps
> * Shared UI elements
> * Gaia Apps
> = 'Gaia'?
> => The FxOS startup process should be separate from describing
> the layers
> => The App Execution Environment ("Apps Architecture") should be
> its own section.
>
> => Feature Support Chart had better happen after explaining that
> there are 3 Runtime Environments: Device, Emmulator, Desktop.
> Actually, that should be part of the initial 'Introduction'.
> => Settings list should be part of the 'Web App Environment' It is
> not related to the Platform.
> => Developer Settings should be part of the Web App Hacking Guide
> which is should be a separate section here but might be in a
> different part of the dev.moz.org site. They are not part of the
> 'Platform'.
>
> Build and Install:
> => we've talked about this.
> => installing on a mobile device should also explain about working
> with the AOSP tools: adb and fastboot. That is the Android
> tradition. Also, it makes more sense to work from full filesystem
> images than relying on the magic of ./flash.sh
> => Dual boot... should be part of a device specific discussion
> subsection.
>
>
> Hacking:
> => this is mixing working on the OS and working on apps
>
> Developer Phone Guide:
> => The initial section 'Firefox OS phones' is missing from the menu.
> ! That's where the device <-> codename mapping lives!
> => The sections should all be different phone names: "Updating..."
> is way too long a title.
> => Is this 'developer' phone or just a 'phone' guide? Once you root
> the phone, the Alcatel thing is just as much a developer phone as
> any other.
> => Troubleshooting should be an overview of "Working with physical
> devices"
>
>
> Release notes:
> => API support does not belong buried here.
> => App permission does not either.
>
>
> App Design and Development:
> => link broken when right-clicking on the title (goes to Release#)
> => This is a separate effort that will need organizing in its own
> right.
>
>
>
>
> All in all there is lots of material here. If it can be systematically
> organized, it provides a good scaffolding for the future. But someone,
> probably you, needs to come up with a coherent outline of the whole thing so
> it is clear to all what goes where.
>
> For example, the Introduction could be:
> Defn: FxOS is a lightweight OS that runs user applications in an HTML
> web page like environment. FxOS is designed to run on mobile
> devices like smartphones and tablets.
>
> Benefits: It's free software.
> It's
[b2g] The dev.moz.org docs
On 12/13/13, 1:00 PM, Chris Mills wrote:
On 13 Dec 2013, at 14:51, Adrian Custer wrote:
You are lost in a maze of twisty pages, all alike…
This is definitely a thing I need to work on. There is a lot here,
and it could use some improved IA. I kind of got to the point where I
couldn’t see the wood for the trees with this section of the site, so
I left it for a while and went on to other things. Again, any ideas
will be listened to ;-)
Do you have a higher level overview of the docs? The current
organization seems kind of strange. When I was writing the Gnumeric
Manual, I needed a clear outline just to keep my own mind clear of what
goes where. We surely need something similar to all be on the same page
when working collaboratively on a wiki.
The current layout lacks a coherent logic. Working from the left-hand
menu on:
https://developer.mozilla.org/en-US/Firefox_OS
(Note that right clicking on each top level element opens an extra page
for that top level element.)
Introduction:
=> Is this focused at everyone or just developers? A key question is
who is tragetted by these docs and how can we redirect the other
readers quickly to other docs.
=> Needs a clear purpose (ie. Hardware requirements is strange to find
here.)
Usage Tips:
=> These are tips for developers, i.e. not 'usage'
Platform Guide:
=> Needs to start with a simple archi diagram:
[ Gaia Web Apps ] [ Other Web Apps]
[ Gecko ]
[Gonk: kernel, drivers, libs ]
=> Needs to work systematically through the layers:
* Kernel
* Drivers and libs
= Gonk
* Gecko
* Web App Security Control
* Web App APIs
= 'Gecko'?
* Common libraries for Web Apps
* Shared UI elements
* Gaia Apps
= 'Gaia'?
=> The FxOS startup process should be separate from describing
the layers
=> The App Execution Environment ("Apps Architecture") should be
its own section.
=> Feature Support Chart had better happen after explaining that
there are 3 Runtime Environments: Device, Emmulator, Desktop.
Actually, that should be part of the initial 'Introduction'.
=> Settings list should be part of the 'Web App Environment' It is
not related to the Platform.
=> Developer Settings should be part of the Web App Hacking Guide
which is should be a separate section here but might be in a
different part of the dev.moz.org site. They are not part of the
'Platform'.
Build and Install:
=> we've talked about this.
=> installing on a mobile device should also explain about working
with the AOSP tools: adb and fastboot. That is the Android
tradition. Also, it makes more sense to work from full filesystem
images than relying on the magic of ./flash.sh
=> Dual boot... should be part of a device specific discussion
subsection.
Hacking:
=> this is mixing working on the OS and working on apps
Developer Phone Guide:
=> The initial section 'Firefox OS phones' is missing from the menu.
! That's where the device <-> codename mapping lives!
=> The sections should all be different phone names: "Updating..."
is way too long a title.
=> Is this 'developer' phone or just a 'phone' guide? Once you root
the phone, the Alcatel thing is just as much a developer phone as
any other.
=> Troubleshooting should be an overview of "Working with physical
devices"
Release notes:
=> API support does not belong buried here.
=> App permission does not either.
App Design and Development:
=> link broken when right-clicking on the title (goes to Release#)
=> This is a separate effort that will need organizing in its own
right.
All in all there is lots of material here. If it can be systematically
organized, it provides a good scaffolding for the future. But someone,
probably you, needs to come up with a coherent outline of the whole
thing so it is clear to all what goes where.
For example, the Introduction could be:
Defn: FxOS is a lightweight OS that runs user applications in an HTML
web page like environment. FxOS is designed to run on mobile
devices like smartphones and tablets.
Benefits: It's free software.
It's a familar develop. environment. Mozilla provides help
(ie docs, the store).
It leverages Android so device makers know the basics and
it can be widely ported.
?Overview of the OS: 3 layer view
?Overview of OS Execution Environment(s)? Devices, emulators... API
?Current status of use, deployments...?
but that takes someone making a coherent outline of the whole thing.
cheers,
~adrian
___
dev-b2g mailing list
dev-b2g@lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-b2g
