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: > > > > > 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
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. 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 find that there are still some errors and warnings. _______________________________________________ dev-b2g mailing list [email protected] https://lists.mozilla.org/listinfo/dev-b2g
