James, thanks so much for your thoughts and input on the demo portal. Comments inline:
> - Show the use of components in a more meaningful context (which Jonathan's > been doing a lot of really good work on) Agreed, and yes, that's what we're working on. > - Provide a high-level description of the component (which the portal > provides; but I think this can be duplicated and moderately extended for the > demo page itself--in this way, the demo pages can be linked to independently > of the portal while simultaneously providing clarity about what the component > does) > - Provide links to further reading on the component: API, tutorials, etc. > - Provide a list of features and functionality of the component (i.e., value > assertion) That's a very good point: This information is on the portal page, but not on the actual demo page. This should be reasonably easy to address. Of course, some design suggestions for how to fit the description (and the other things you suggest) into the page would be greatly appreciated :-) > - Provide useful, succinct code snippets + ultra-light documentation to give > integrators a taste for how easily the component can be inserted and > manipulated The code itself, and the mark-up, need to have more "documentation-style" comments in them. This is one place where we do want to state what might be obvious to *us*. Another thing we plan to do is use the demo code as the basis for a tutorial that will walk the reader through all that needs to be done. Do you think more instructive comments plus a link to a tutorial would address this point? > - Package the full demo code and make it available for download and tinkering > (we might consider adding a readme or other documentation to accompany the > package). The demo code is already part of the downloadable Infusion bundle, in a top-level folder called "demos." Do you think this is adequate, or are you thinking of something else? > Also, I suspect that making the complete code available for reading directly > beside the demo may not be as useful as we might've initially reasoned. It'll > be a good deal of code once we finish implementing the new component designs > Jonathan has been coming up with, and the initial demo page may not be the > choice environment for an integrator to look through all that code. Succinct > pieces of relevant code might have better impact. We've actually had feedback from users that the current demo portal is "incredibly helpful." I think we do need to try to keep the demos as clean as possible, and simple enough to minimize code that's unrelated to the component we're actually demonstrating. Also, clear comments stating "Here's where the component is being used" will help reader to separate the wheat from the chaff. Currently, the tabs showing the code are actually generated by JavaScript that loads the actual demo code itself. Changing this to show only relevant snippets might require we switch to a method that's probably more tedious to maintain. > Making these sorts of changes to the demo pages might take a bit of time, so > we wouldn't need to make them happen alongside the current round of demo > updates. However, more demo updates are scheduled on the roadmap for Infusion > 1.4, so if we do go ahead with changes, maybe it'd fit well within that time > frame. I agree that we should be able to proceed with changes in stages. There's no reason we couldn't start with some of the simpler things in time for 1.3 (like including the high-level description and the links to more info on the demo page itself). We should also try to improve the comments in the new demos we've just written (i.e. Progress and Inline Edit) while they're still fresh in our minds. -- Anastasia Cheetham Inclusive Design Research Centre [email protected] Inclusive Design Institute OCAD University _______________________________________________________ fluid-work mailing list - [email protected] To unsubscribe, change settings or access archives, see http://fluidproject.org/mailman/listinfo/fluid-work
