Documentation Redesign Notes
Infusion Documentation
The process of developing this information, along with the related mind maps, have led to the development of a proposed architecture for the Infusion Documentation. The latest version of the proposal can be found at Documentation Architecture - Round 2.
Goals
- Introduce visitors to Infusion: What it is, what it offers.
- Also the same goal as the Component Demos (jh)
- Teach the concepts and practices we use in Infusion.
- Guide all audiences in using the Infusion Framework and Components.
Audiences
Web developers with varying backgrounds:
- HTML and CSS, no JS
- Some JS experience, with knowledge of jQuery or something similar
- Experienced JS developers (including in-house developers)
Audiences will also have different knowledge of Infusion:
- Brand-new to Infusion
- Experienced with using Infusion
This appears to be a slight subset of the audience for Component Demos. Audience for Component Demos also includes non technical users. (jh)
Scenarios
- Advanced developer, new to Infusion
- Beginner developer, knows Infusion, specific goal
- Beginner developer, new to Infusion
- Advanced developer, new to Infusion
- Advanced developer, knows Infusion, advanced goal
- Experienced developer, new to Infusion, basic goal
- Experienced developer, new to Infusion, advanced goal
- Experienced developer, new to Infusion, accessibility goal
- Web designer, new to Infusion, wants better CSS
Advanced developer, new to Infusion
Name: Neal
Background: experienced developer, Java background, very good JS. Works on a large dev team. Boss said "Go check out this Infusion thing. Find out if it's something worth using."
Goal: Learn about Infusion.
Neal finds the main Fluid Project site and clicks "Learn about Infusion." He starts with the demos, trying each one out and looking at the sample code. Impressed with the configurability of the components, he goes back to the "Learn..." page and follows links to information about the Framework itself. As he reads about the principles embodied in the Infusion code and the designs and practices used, he becomes more and more impressed. As he reads about the Renderer, he realizes something about its strengths that he didn't quite grasp just looking at the demos. Luckily, there is a link on the page to the demos, so he uses it to quickly go back and try the demos with the new insights in mind. He returns to the Framework documentation and reads about the IoC system. Recognizing the concepts from his work in Java with the Spring framework, he's surprised to see something like this available in a JavaScript framework. He reports back to his boss that Infusion is something that is definitely "worth using."
Beginner developer, knows Infusion, specific goal
Name: Jamie
Background: Web developer with some Javascript. Has added the Uploader out-of-the-box to his application (cutting and pasting the markup).
Goal: Customize the markup for the Uploader interface
Jamie has created an HTML template for what he wants his application's Uploader interface to look like. He turns to the Uploader API page and looks at the list of selectors described there. He understands what the selectors are for based on their name, but he's not sure how to apply them to his different markup (should a selector go on the <ul>? on the <div> around the <ul>?). Jamie follows a link on the API page to the Uploader Demos page. Here, he finds several different Uploader interfaces with different markup. By looking at where the selectors are on each of these examples, he comes to understand how to use them in his markup.
Beginner developer, new to Infusion
Name: Mateo
Background: self-taught javascript hacker; very enthusiastic; came across Infusion, thinks it looks cool
Goal: Add Inline Edit to site
Mateo pokes around the Infusion site, looks at the demos, and thinks the Inline Edit is perfect for an image library application he's putting together. He follows a link on the Inline Edit demo page called "How to add the Inline Edit to your application." ...
Advanced developer, new to Infusion
Name: Minerva (Minnie)
Background: experienced developer, Java background, very good JS. Works in the IT department of a large private school. Boss said "Go check out this Infusion thing, see if it has anything that will help with our student roster. Joe said they have some kind of pager"
Goal: Learn about Infusion, add Pager to site
Minnie finds the main Fluid Project site and clicks "Learn about Infusion." She reads the marketing-speak and is intrigued. She follows the "Demos" link and finds the Pager. After playing with the Pager demos and reading a bit about it on the demo page, she thinks it's worth looking closer. She uses the link on the demo page to get to the Download page and downloads the source distribution. Back on the demo page, she follows a link called "How to add the Pager to your application." ...
Advanced developer, knows Infusion, advanced goal
Name: Valeriya
Background: Experienced JS developer, has worked with Components and a few Framework functions; has looked at the innards of a few components
Goal: Wants to create her own Picture Gallery component using Infusion
Valeriya starts creating her Picture Gallery component by sketching out the basic creator function and defaults declaration, as she has observed in the Infusion source code. As she expands the code, she suspects that she'll want to encapsulate a particular piece of functionality as its own component, and have her Picture Gallery component use it. As she tries to implement this, she realizes that she doesn't quite understand how dependencies work, so she scans the main Infusion Documentation page. She sees words like "components" and "framework," but nothing that looks like it will help with dependencies. There is a link titled "How do I ... ?" Hoping that she might find something relevant, she follows the link. On the "How do I" page, she follows a link titled "How do I declare dependencies?" The resulting page has an explanation of the 'fluid.demands' function, some examples, and links to background and related information. She decides that she'd better read some of the background before continuing, so she starts with "About Infusion IoC."
Experienced developer, new to Infusion, basic goal
Name: Takumi
Background: Experienced JS developer, no experience with Infusion
Goal: wants to create a Drupal module to add UIO to any Drupal site
Takumi is an avid Drupal user and developer. He sees a demo of UIO and thinks it would be a great functionality to add to Drupal, so he decides to create a module for it. He finds the tutorial describing how to add the fat-panel UIO to a site and dives right in. The tutorial references various features of the Framework that Takumi needs to understand in order to build his module, so he starts reading.
What does Takumi need to know about?
(the following list has not yet been sorted into any order)
- grades
- components
- events and listeners
Experienced developer, new to Infusion, advanced goal
Name: Fadilah
Background: Experienced JS developer
Goal: wants to implement a Preferences Editor using the Preferences Framework
Fadilah has seen a demonstration of UIO and is sold on the idea of personalization. Her web application has various features that she's like users to be able to personalize, so she wants to create her own custom preferences editor.
What does Fadilah need to know about?
(the following list has not yet been sorted into any order)
- components
- grades, dynamic grades, grade merging
- adjustors, panels, enactors
- dom binder
- ioc expressions
- distribute options
- renderer, templates, protoTrees
- static environment
- models, model transformation
Experienced developer, new to Infusion, accessibility goal
Name: Darren
Background: Experienced web developer, no experience with Infusion
Goal: Ensure web app is accessible
...
Web designer, new to Infusion, wants better CSS
Name: Mhari
Background: Experienced HTML/CSS user
Goal: Wants a better way of using CSS to lay out pages
...