> On 15 Sep 2015, at 17:37, Fabrice Desré <fabr...@mozilla.com> wrote: > > On 09/15/2015 09:00 AM, Paul Rouget wrote: > >> Any suggestion? > > I don't see any issue with using what you started on github as a > reference, and adding comments in the implementation to remind people > that they need to update the doc when making observable changes.
I think creating some kind of document like Paul’s for Firefox OS APIs would be a great start towards getting documentation done more rapidly and effectively. Ideally i’d like: * WebIDL * Some notes to explain what the members do * A couple of brief code examples to get me started on writing demos * A designated point of contact to bug with questions ;-) Sometimes similar documents are published at, https://wiki.mozilla.org/WebAPI, and these are sometimes helpful, but not always. The implementation bugs are rarely helpful, as there is so much dense information there. I often just end up looking at the webidl files on dxr, and guessing until I can find an engineer to bug for info (not too hard - most of you are super helpful! But I appreciate you are crazy busy too.) If producing a doc like Paul’s was in the workflow, I could just monitor that for changes, and all would be great. In terms of getting updates into the docs workflow, adding the dev-doc-needed keyword is really useful. At a push, it would be useful to just file a developer documentation bug saying “this API’s docs are really outdated. Please fix”, or similar. At least then they would show up on our map. _______________________________________________ dev-b2g mailing list dev-b2g@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-b2g
