On 1/3/2011 1:44 PM, Hossein Haeri wrote:
This is though not encouraged at all and I don't really think that the documentations of Fusion and Proto are that nicely tied.
Suggestions for improvement are welcome.
Sure. Here are some suggestions:
1) Every now and then in the Proto documentation, you can add a short intermezzo which explains which Fusion creature is used in that specific point and how.
Fusion is used in *very* few places in Proto. Only unpack_expr and fold use any part of Fusion, and the reference for those make it pretty clear the dependence on Fusion.
2) You might want to state Fusion as a pre-requisite for proper Proto knowledge.
Let me ask you this: what about Proto specifically have you found difficult to understand without Fusion knowledge? I could focus my attention there.
3) After "Getting Started" and before "Fronts Ends...", you might stitch in a short summary of what Fusion is, what it does for Proto, and perhaps a quick hand-wavy explanation about the parts of Fusion that would be handy in development using Proto. Obviously, this will have links to appropriate corners in the Fusion documentation.
I'm not (yet) convinced it's necessary, and I certainly don't want to document Fusion even in hand-wavy terms. It's a maintenance burden to have to keep it in sync with the actual Fusion documentation. I wish our document toolchain made cross-linking in our docs easier. That's the way to go, IMO.
On the other hand, the documentation of Fusion is rather a reference manual and you'd usually not learn how to program using a library by reading the mere reference...
Yeah, the Fusion docs could use more users'-guide-ish docs for its high-level architecture, concepts, and common usages. -- Eric Niebler BoostPro Computing http://www.boostpro.com