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 [email protected] || @chrisdavidmills On 13 Dec 2013, at 15:54, Adrian Custer <[email protected]> wrote: > 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
