What needs documenting in B2G?

We may be contracting out to help get the core B2G docs up to date. By 
that, I mean, things other than Web-facing stuff. Things like core 
libraries, architecture, that kind of thing.

Anyone aware of things that need documenting or their docs updated? I'm 
building a list for the statement of work, so don't be shy! If it 
matters to you, let me know!

-- 
Eric Shepherd
Developer Documentation Lead
Mozilla
Blog: http://www.bitstampede.com/
Twitter: @sheppy

0
Eric
6/14/2013 2:10:56 PM
mozilla.dev.b2g 4036 articles. 0 followers. Post Follow

2 Replies
564 Views

Similar Articles

[PageSpeed] 38

On 2013-06-14 15:51:14 +0000, Gabriele Svelto said:

> Will this documentation be oriented towards developers who might 
> actually want to work on the B2G core (gecko, gonk, platform stuff, 
> porting, etc...)?

Yes, some of it. This documentation is for people that want to work on 
B2G core, porting, and customizing the OS for new phones and carriers.

> There's quite a few areas of our code which will appear pretty obscure 
> to anybody seeing them for the first time without some form of 
> documentation. I was working myself on a document on our memory 
> management policies which would cover low-memory detection, memory 
> pressure events, OOM killer policy, priorities and so on.

Yes; that's what we're trying to fix. Having docs like that on MDN 
would be a big help for newcomers.

> The biggest problem with this kind of documentation is that it always 
> risks ending up outdated; how do we encourage developers to keep it up 
> to date once it's done? Outdated documentation can often be worse than 
> no documentation at all and B2G has been a pretty fast moving target 
> until this point.

One way to help relieve that is to provide overviews on MDN, with links 
to the appropriate source code so people can see the latest material 
for themselves. If the code is well documented in and of itself (which 
usually Mozilla's code is not, unfortunately), that can work well.

Otherwise, we have to incentivize developers to help us keep the code 
up to date. We're working on tools to help make that easier. One thing 
we hope to do eventually is actually have it so documents can be 
"linked" to source files, so that when that source changes, a flag goes 
up on the doc to indicate that it should be checked to be sure it's not 
out of date.

-- 
Eric Shepherd
Developer Documentation Lead
Mozilla
Blog: http://www.bitstampede.com/
Twitter: @sheppy

0
Eric
6/14/2013 4:20:31 PM
On Friday, June 14, 2013 9:20:31 AM UTC-7, Eric Shepherd wrote:
> On 2013-06-14 15:51:14 +0000, Gabriele Svelto said:
>=20
>=20
>=20
> > Will this documentation be oriented towards developers who might=20
>=20
> > actually want to work on the B2G core (gecko, gonk, platform stuff,=20
>=20
> > porting, etc...)?
>=20
>=20
>=20
> Yes, some of it. This documentation is for people that want to work on=20
>=20
> B2G core, porting, and customizing the OS for new phones and carriers.
>=20
>=20
>=20
> > There's quite a few areas of our code which will appear pretty obscure=
=20
>=20
> > to anybody seeing them for the first time without some form of=20
>=20
> > documentation. I was working myself on a document on our memory=20
>=20
> > management policies which would cover low-memory detection, memory=20
>=20
> > pressure events, OOM killer policy, priorities and so on.
>=20
>=20
>=20
> Yes; that's what we're trying to fix. Having docs like that on MDN=20
>=20
> would be a big help for newcomers.
>=20
>=20
>=20
> > The biggest problem with this kind of documentation is that it always=
=20
>=20
> > risks ending up outdated; how do we encourage developers to keep it up=
=20
>=20
> > to date once it's done? Outdated documentation can often be worse than=
=20
>=20
> > no documentation at all and B2G has been a pretty fast moving target=20
>=20
> > until this point.
>=20
>=20
>=20
> One way to help relieve that is to provide overviews on MDN, with links=
=20
>=20
> to the appropriate source code so people can see the latest material=20
>=20
> for themselves. If the code is well documented in and of itself (which=20
>=20
> usually Mozilla's code is not, unfortunately), that can work well.
>=20
>=20
>=20
> Otherwise, we have to incentivize developers to help us keep the code=20
>=20
> up to date. We're working on tools to help make that easier. One thing=20
>=20
> we hope to do eventually is actually have it so documents can be=20
>=20
> "linked" to source files, so that when that source changes, a flag goes=
=20
>=20
> up on the doc to indicate that it should be checked to be sure it's not=
=20
>=20
> out of date.
>=20
>=20
>=20
> --=20
>=20
> Eric Shepherd
>=20
> Developer Documentation Lead
>=20
> Mozilla
>=20
> Blog: http://www.bitstampede.com/
>=20
> Twitter: @sheppy

Linking code to docs seems like a smart idea. As I'm coming up to speed on =
Firefox OS (not my first OS), I'm noticing that some part of the docs seem =
out of sync with other parts.=20

I'm really excited to hear that you're going to be upgrading the docs. Poor=
 docs can hurt the rapid growth needed for Firefox OS to survive. I had to =
do a little bit too much trial and error to get a working build, only to fi=
nd that there are still some errors and warnings.=20



0
Bob
6/23/2013 7:25:38 AM
Reply:

Similar Artilces:

[signin][b2g] - B2G->dev merge
We have been discussing forceAuthentication, but there are other B2G features that must be merged into dev. So that JedP and I can prioritize, bisect, and tackle, can we get a list of features and any dependencies they have on other features? Off the top of my head I know of: * forceAuthentication * forceIssuer * allowUnverified * special TOS/PP handling - in B2G, TOS/PP links must be opened in an IFRAME instead of in a new tab. * A way of indicating experimental features Are there other new features that I am missing? We are actively discussing forceAuthentication, but t...

b2g-info now subsumes b2g-procrank and b2g-ps
Dear all, I just merged b2g-info, a tool which gives you information about b2g processes running on a device, into gonk-misc. You can get this new tool by running ./repo sync and then rebuilding with ./build.sh. b2g-info is meant to subsume b2g-procrank and b2g-ps. It (hopefully) outputs all of the useful information from b2g-ps, b2g-procrank, b2g-procrank --nice, and b2g-procrank --oom plus some additional data in a (hopefully) easier-to-digest format. b2g-info is also faster than b2g-procrank, which makes a difference if you're running b2g-info repeatedly from a script. ...

Merging dev-gaia and dev-b2g into dev-fxos
--001a113ce93ebce35d051e4c0c73 Content-Type: text/plain; charset=UTF-8 Hello people of Firefox OS, After a discussion we have decided that the distinction between dev-gaia and dev-b2g mailing lists is not enough to warrant maintaining two lists. So we are deprecating both in favor of dev-fxos. So if you are subscribed to one of the aforementioned lists, you will be subscribed to the new dev-fxos list and we will shortly be decommissioning dev-gaia and dev-b2g. Thanks! Michael --001a113ce93ebce35d051e4c0c73 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: qu...

Merging dev-gaia and dev-b2g into dev-fxos
--001a113ce93ebce35d051e4c0c73 Content-Type: text/plain; charset=UTF-8 Hello people of Firefox OS, After a discussion we have decided that the distinction between dev-gaia and dev-b2g mailing lists is not enough to warrant maintaining two lists. So we are deprecating both in favor of dev-fxos. So if you are subscribed to one of the aforementioned lists, you will be subscribed to the new dev-fxos list and we will shortly be decommissioning dev-gaia and dev-b2g. Thanks! Michael --001a113ce93ebce35d051e4c0c73 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: qu...

dev.b2g and dev.gaia redundancy?
I'm relatively new to the project but I see more overlap than not lately in the dev.b2g and dev.gaia newsgroups. Are the original motivations for having distinct groups still still applicable? Would things be easier for more people if we collapsed down to one group? Is that an awful idea? - A +1, half the emails are sent to both lists to take it further I am sitting alone in #fxos on irc On 4 December 2013 00:22, Asa Dotzler <asa@mozilla.com> wrote: > I'm relatively new to the project but I see more overlap than not lately > in the dev.b2g and dev....

blocking-b2g / feature-b2g / status-b2g-v2.5 change for FxOS 2.5 in Bugzilla
--Apple-Mail=_A344D24D-898F-4783-9B3E-33CDD840A153 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=utf-8 Dear b2g friends, Just to inform you the following change has been applied to Bugzilla = since we have announced FxOS 2.5: 1. blocking-b2g and feature-b2g flags are renamed from 3.0?/+ to = 2.5?/+. 2. New tracking flag status-b2g-v2.5 is created. Sincerely, ------------------------------------------------------- Josh Cheng Engineering Project Manager, Firefox OS Mozilla Corporation =E2=9C=89 joshcheng@mozilla.com <mailto:joche...

B2G debugging documentation
I'm working away at debugging related docs pertaining to Firefox OS. Lots of changes here: https://developer.mozilla.org/en-US/docs/Mozilla/Boot_to_Gecko/Debugging_on_Boot_to_Gecko We also now have: https://developer.mozilla.org/en-US/docs/Mozilla/Boot_to_Gecko/Debugging_on_Boot_to_Gecko/Setting_up https://developer.mozilla.org/en-US/docs/Tools/Debugger And next week, I'll be working further on: https://developer.mozilla.org/en-US/docs/Mozilla/Boot_to_Gecko/Debugging_on_Boot_to_Gecko/Using_the_Remote_Web_Console Please feel free to tweak these if you see any proble...

mailman config changed; text/html should now show up in dev-gaia and dev-b2g and links should not be corrupted
This is a multi-part message in MIME format. --------------040907020305070007060305 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Assuming all has gone well, the mailman list-server software we use for dev-b2g and dev-gaia should no longer force multipart/alternative mail messages to use the first sub-part (which is likely to be text/plain). What this means is that if you use the gmail web UI to talk on the list and your hyperlinks have ended up messed up, that should stop happening. (This, by definition, is/was a bug in gmail'...

mailman config changed; text/html should now show up in dev-gaia and dev-b2g and links should not be corrupted
This is a multi-part message in MIME format. --------------040907020305070007060305 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Assuming all has gone well, the mailman list-server software we use for dev-b2g and dev-gaia should no longer force multipart/alternative mail messages to use the first sub-part (which is likely to be text/plain). What this means is that if you use the gmail web UI to talk on the list and your hyperlinks have ended up messed up, that should stop happening. (This, by definition, is/was a bug in gmail'...

I have chmod 0755 /system/b2g/b2g error = -30
Hi everyone, I have the loglevel 8 in init.rc and I have the next error messages: ============ init: processing action 0x351f0 (fs) ehci_fsl_bus_suspend begins, Host 1 ehci_fsl_bus_suspend ends, Host 1 UBIFS: mounted UBI device 0, volume 0, name "system" UBIFS: mounted read-only UBIFS: file system size: 229318656 bytes (223944 KiB, 218 MiB, 1806 LEBs) UBIFS: journal size: 9023488 bytes (8812 KiB, 8 MiB, 72 LEBs) UBIFS: media format: w4/r0 (latest is w4/r0) UBIFS: default compressor: none UBIFS: reserved for root: 0 bytes (0 KiB) UBIFS: start fixing ...

Documentation for debugging on B2G and Gaia
I'm starting work on documentation for debugging of B2G itself as well as of Gaia apps, and I'm soliciting opinions as to what topics are the most interesting and most important. If you have thoughts on this, please let me know! Eric Shepherd Developer Documentation Lead Mozilla http://www.bitstampede.com/ ...

Documentation for debugging on B2G and Gaia
I'm starting work on documentation for debugging of B2G itself as well as of Gaia apps, and I'm soliciting opinions as to what topics are the most interesting and most important. If you have thoughts on this, please let me know! Eric Shepherd Developer Documentation Lead Mozilla http://www.bitstampede.com/ ...

Is there/where is B2G device APIs documented?
I'm just getting started with B2G and looking for the device APIs, I've spe= nt 1/2 an hour going through all the documentation and links I could find o= n the B2g home page but was unable to find them. Do they exist?=20 In particular I'm wondering if there is an SMS API? I would like to write a= n app that is capable of intercepting application directed (as opposed to u= ser directed) SMSs. This is something possible with native development (And= roid, Brew, Symbian etc.) and I'm looking for the same with a B2G html5 app= .. If no such API currently exists, is it i...

B2G update expectations (was: Re: Gecko 17 as the base for B2G v1)
On Thu, Aug 2, 2012 at 10:20 AM, Asa Dotzler <asa@mozilla.org> wrote: > On 8/2/2012 12:07 AM, Gijs Kruitbosch wrote: > >> Which brings me to another question: how long do you expect to keep B2G >> on Gecko 17? (eg. will v2 be off 17 or off the next ESR or off something >> else still?) Fragmentation on eg. Android is well-documented, what's the >> plan in that department? > > Fragmentation is something we will eventually need to plan to avoid. Is there a plan that involves offering eventual Gecko updates OTA to devices that initially shi...

Web resources about - What needs documenting in B2G? - mozilla.dev.b2g

Self-documenting - Wikipedia, the free encyclopedia
Self-documenting code is ostensibly written using human-readable names, typically consisting of a phrase in a human language which reflects the ...

1 documenting - Flickr - Photo Sharing!
Wesley mans the video camera.

Footage Documenting Harvey Milk's Assassination and Dan White's Arrest - YouTube
From the award winning documentary "The Times of Harvey Milk". I would have uploaded more of this great documentary but to create this I needed ...

Documenting with dignity in the Ebola zone
Brisbane Times Documenting with dignity in the Ebola zone Brisbane Times I have taken pride over my 40-plus years as a photojournalist in ...

Cabinet leaks continue with release of email documenting Government talking points, responses
A leaked document reveals what Federal Government MPs have been told to say in response to questions about Cabinet's agenda.

Map: Documenting Scouts-related sex abuse cases
Documenting Scouts-related sex abuse cases

Google Street View documenting Sandy’s aftermath: reports
A move by Google to document Hurricane Sandy’s devastating aftermath with its Street View technology has stirred up controversy.

Content Pointer: Documenting Exploratory Testing
My latest testing article is on documentation and exploratory testing. You can read an online version here: Documenting Exploratory Testing. ...

Documenting Software Architectures
You have more chances to like a book on documenting software architectures when the authors know how to write and this is the case for this one. ...

Documenting life under ISIL
Al Jazeera meets journalists who tell stories from Mosul from their computers in Kurdish-controlled northern Iraq.

Resources last updated: 11/29/2015 3:11:25 PM