reorganize documentation about chromeless

[lloyd]

oh, one thing I didn't mention is a simple step we can take in the future is a little toggle in the doc system. So you can specify who you are, and information will be filtered accordingly. Beginner, intermediate, expert, or by type, whatever. This way a new developer landing on the documentation will see only the highest level apis, and can then flip the switch when/if he gets into module development

[taboca]

Important to point out that we were not exposing this whole documentation based on the jetpack modules before. Our prior goal was to simply be webby -- so in that sense, documentation = web standards, with some exceptions -- indeed a reason to have some modules documented = whitelist of chromeless modules. The more we tend to solve the whole documentation system ( of platform, Jetpack ( Firefox ) and Chromeless ) a side of me tends to say: great; another side says: this can be out of the scope of Chromeless, or should have to do with other projects too.

( Brainstorming pause section )

One side of me tend to think the documentation could be the HTML-based examples and tests. So in that sense a module documentation would not be exactly the module, but the HTML that tries to use the module. The collection of the usage becomes the actual inference about documentation about the actual target module is being use. It's like making a test case the documentation instead trying to make the module source the one. Quite weird right?

( back to current )

I do think the work you did is great, and with a Chromeless 0.2/0.3 biased mindset I would say = toggle ON first, let's keep it simple. Chromeless-kit = browser-based apps. Specifically toggle mode 0.1 = webby way of doing and show examples and documentation for them. Toggle 0.2/0.3 where we are that can be a bit more platformy. I am not sure about this structure should be related to the code structure. Is it too weird to keep things flat and make a tag structure that is why documentation is for? So Webby tag = composition of { api-utils subset, chromeless-kit subset ). Just a thought. And keep simply reusing Jetpack for now too.

Maybe we should pitch jetpack documentation folks about this too. This is important discussion for Mozilla wise.

[lloyd]

@taboca

With respect to this general crazy focus I've been putting on docs, I agree -- its a very 0.3y issue. We could be instead focusing on exploring and building new features. The short answer is I got really interested in the problem, and feel like we're very close to having a framework in place that will be low cost to maintain. I strongly believe we can do both - explore crazy ideas with chromeless AND support people in the community releasing production quality products. But I feel like good documentation is fairly simple to produce if its really convenient and easy to write.

As far as emphasizing code samples as a means of documentation, I love it. I think it'll be fairly simple to integrate them into the doc system.

Finally, regarding tags vs. packages as a means of putting pkgs in a logical structure... I don't know. Both have their merits. I agree we should engage the addon-sdk folks and see if we can figure out a lightweight way to share modules first. That discussion may affect how we use packages. Check out Issue #53 for the start of the conversation :)

One reason I lean toward using packages for dev facing structure as well as file system structure is that it's one less thing to maintain. If the decision of where to place a new module in the repository also ends up generating reasonable docs, that reduces the maintenance cost of our doc system and gives it a better chance of aging well. Same philosophy here as motivated the embedding of documentation in js source... Perhaps sacrifice a little bit of flexibility in order to gain maintainability.

That said, I'm still personally undecided, and think both approaches have merits.