Le 30/07/2012 12:02, Till Schneidereit a écrit :
After some discussion on IRC, Eddy and I have started an Etherpad to
collect things we might want to do to improve our docs:
https://etherpad.mozilla.org/sm-doc
I made one thing the first entry in that list as I think it could be a
big imrovement: How about getting someone to look at the docs from a
usability POV? Structuring docs in such a way that they're accessible
to newbies is quite a challenge, and from my recent experience with
consuming them in that role, I know that our docs are far from perfect
in that regard.
I volunteer to be a guinea pig here.
I know some concepts used in the engine (JIT, Shape, etc.), I know a bit
of C and C++, I know JavaScript.
I follow some bugs and make my best to learning through reading code
reviews, but I lack the bigger picture, I don't know how the
SpiderMonkey code is structured. I contribute documentation to MDN (I'm
even the "JavaScript topic driver" as it's called), so I have some
experience in structuring doc, especially to target newbies.
I think that one thing that lacks so far is a broad architecture
diagram. I mean a recent one and I mean in the form of an image, maybe
several even. I don't know where to find one. There is
http://hacks.mozilla.org/2010/03/a-quick-note-on-javascript-engine-components/
, but at the rate of 1/4th of the engine rewritten a year, half of the
engine has changed by now, and I don't know what credit give to that.
Likewise, is https://developer.mozilla.org/En/SpiderMonkey/Internals
up-to-date?
Unfortunately, knowing that doesn't mean that I also know how to
improve their structure in general.
The main question to answer to find a good structure for documentation
is: what are people looking for? What question do they try to answer in
the doc? Once, Tom mentioned a stackoverflow-like platform for the JS
engine team (I can't remember the URL). There is definitely
documentation material on that platform. It probably just takes the time
to port the information over to MDN.
Knowing JavaScript, but not knowing SpiderMonkey, I have some questions
like (some are naive and i could probably find the answer easily, but
that's a taste of what newbies may be wondering):
1) How are JS values stored?
2) How are JS objects stored?
3) If I want to implement the mustache operator, what does it take?
4) When I start the REPL, what preparation code runs before I type?
My experience in reading code reviews is that they are very helpful in
understanding the modified code. It may be extremely relevant to point
to implemented feature diffs.
Also, although the point is not to document other engines, having
answers for V8 and JSC could be valuable in terms of "they do it this
way in such engine, but we do it this way", which can help bridging from
contributing to one JS engine to another.
Should also be documented anything that isn't in code and cannot really
be in comments (most often because what needs to be explained is not
local to the line or couple of lines). My guess is that if you track
these things on a daily-basis, you will end up with a lot of things to
document and won't do them. An idea is that you keep a TODO-list as in
https://developer.mozilla.org/User:dbruant/TODO Just a line per item to
document. And once in a while, you go over that list. If you don't do it
naturally, organize a docsprint once every 2 months while the entire
team works on documentation for 2/3 days. Documentation may be annoying,
but it's much more motivating when everyone is doing it.
So yeah, besides a "SpiderMonkey map" and answer to questions like the
above, I don't really know what to suggest. My advice about the
documentation structure would be the following: write a first draft and
ask for reviews. I'll do a review of this draft.
(And I don't really mean improving
their content - it's clear that creating good documentation and
keeping it up to date takes vast amounts of time.)
Especially keeping it up, I agree. I am very positive at the idea of
improving the doc, but I think it should be a continuous work.
Documentation should be part of the product. Web developers LOVE the
"new in firefox X" pages, because it helps them keeps track of what has
changed regularly. There is probably a need to do the same thing for the
JS engine (and every piece of software?).
FYI, the MDN team is gathering next week to discuss new features to add
to the new documentation wiki (which recently switched from a contract
to a in-house product), so if there is anything that stops you from
writing doc or good doc or getting started or anything, just tell me,
I'll share the info and see what can be done in a timely manner.
Tom wrote:
- Events/Conferecens
Not sure yet.
I have the feeling that I don't see enough talks on SpiderMonkey. For
sure, recently, I see less talks on SpiderMonkey than on V8 and I'm
convinced there is no less to say.
Maybe I'm wrong and look at the wrong place, but SpiderMonkey seems less
visible from the outside world. Make it visible, show your work!
David
_______________________________________________
dev-tech-js-engine-internals mailing list
[email protected]
https://lists.mozilla.org/listinfo/dev-tech-js-engine-internals
