On 12/13/13, 1:00 PM, Chris Mills wrote:
On 13 Dec 2013, at 14:51, Adrian Custer <[email protected]> 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.
AAAAHHHH! 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
[email protected]
https://lists.mozilla.org/listinfo/dev-b2g
