Infusion Documentation Testing April 15, 2015

For the Community Meeting on April 15, 2015 we spent the time testing the Infusion Documentation.

We took notes on Pirate Pad at http://piratepad.net/ny3ADJKalK and they are reproduced below:

 

Simon: Tutorials, IE11 Windows
Sepideh: Infusion dComponents, Inversion of Control, Events, Safari
Jon: FF, Infusion docs section Change Applier onwards.
Dana: Chrome, Infusion 
Anastasia: Prefs Framework, General on IE11 Windows
Michelle: FF, Tutorials

Priorities:

  • Fix links going to 404 page
  • Fix links going to the wrong page
  • Decide on URL naming convention:
    • infusion/latest/ ? infusion/in-progress? etc Decided: infusion/development and infusion/<version>

For Later:

  • Fix ChangeApplierAPI.html to API category (Jon - Pull Req.) This will be fixed by FLUID-5791
  • Put Starting with Infusion tutorial and subpages into its own section similar to how Renderer is done (Jon - Pull Req.)

Known Broken Links

- broken link (404) to Infusion Components in first paragraph of Renderer Component Trees
- Link to "Useful functions and events" from last row of table on Component Grades page links to Infusion "Renderer Components" page instead of Tutorial "Renderer Components" page (the former has no section called "useful functions and events"


ChangeApplier.html:
- "model state" link goes to Framework Concepts page, but not immediately clear what the user should read from there. "Model state" isn't even mentioned on the Framework Concepts page.
- Acronym "POJO" is used but not defined. Should we define such terms?
          suggestion: link it to https://en.wikipedia.org/wiki/Plain_Old_Java_Object ?

ChangeApplierAPI.html
- Invoker link goes to "compact" section of that document.
      - should invoker link go to Invoker doc and the "compact" word previous to it go to the "Compact" section of the invoker document?
             - this should be re-examined, since there's nothing in the 'compact' section of the invoker documentation!
Above-mentioned ChangeApplier-related problems files under FLUID-5828 - Getting issue details... STATUS

Renderer.html
- "markup agnoticism" link should link to "markup agnoticism" section of the Framework Concepts document
HowToUseTheRenderer.html
- "parent grade" link should jump to "Specifying parent grades" section of the Component Grades document?
Renderer issues  filed in FLUID-5829 - Getting issue details... STATUS
 
Jon's Notes:

ChangeApplierAPI.html
- wrong category. Should be API, not Infusion section. Will be fixed with FLUID-5791
- Listeners link goes to a document called "Events" which doesn't have content - just 3 links to other documents. Confusing?

HowToUseTheRenderer.html
- fluid.render link goes to specific lines in code in github - these lines may change over time - should we hard-code such references in the docs? Perhaps better to generalize it by saying "See fluid.render on this page".
Renderer issues  filed in FLUID-5829 - Getting issue details... STATUS

Styling Issues:
- Lists are rendered in a smaller font than the rest of the body? Example: Renderer.html
   No, the first paragraph is just in a larger font than the rest of the page

Sepideh's Notes:

Code snippets look very much like buttons
Would be nice for ToC to be "sticky" and separately scrollable
Declarative Configuration: is commonly appearing options the same as component configuration option?
IoC: Component link is broken
-Model Component: the applier, model, and the changeapplieroptions, prototree, producetree, rendererFNOptions anchors in the code snippet is not working
-Event Components:Is listener record similar to Infusion Event System?

-Event Components:Is listener record similar to Infusion Event System?

-Renderer Components: Prortotree link is broken
 -Renderer Components:Produce tree link is broken  
Renderer issues  filed in FLUID-5829 - Getting issue details... STATUS

-Components Grade: Useful functions and events link to Renderer components
-Delivering a dynamic gradeName via an options distribution: mixed links to mixin

In this doc, there are some internal links to section headers, but the section headers are formatted as code, so the anchor name isn't working

Simon's Notes

    • "If you haven't already, you might want read..." missing "to"
  • When you are on a sub-page of a tutorial, there is no indication of your location in the table of contents on the left.
  • The first page of the "Getting started with Infusion" tutorial, "Set up your environment", suggests that you start my visiting a page which has not been converted yet
    • and it has no place in the table of contents
  • In the "Getting started with Infusion" tutorial, we hit a lot of pages that haven't been converted yet "This page is still under construction. An archived version can be found on the Reorderer page of the Infusion Documentation wiki."

Dana's Notes:

- section links not visible in narrow responsive view
- is there any way we can have ToC scroll separately? this would make it possible to always see where you are in ToC (anchor view to current location)
- Understanding Infusion Components - section What Does a Component Look Like - there is a section of text "to customize the component" that is styled like a code block
- Component Grades first table - Description text in first row is much bigger than all the rest

- Link to "Useful functions and events" from last row of table on Component Grades page links to Infusion "Renderer Components" page instead of Tutorial "Renderer Components" page (the former has no section called "useful functions and events"

- broken link (404) to Infusion Components in first paragraph of Renderer Component Trees
Filed in FLUID-5829 - Getting issue details... STATUS

Anastasia's Notes:

  • no focus styling
  • in IE11, github icon is low down, hover styling doesn't cover it
  •  code highlighting overlaps a lot
  • Builder page: formatting of "Return Value" under Parameters isn't working
  • Builder page: Note under Options isn't formatting well as a note Filed in FLUID-5838 - Getting issue details... STATUS
  • Settings Store page has no link to wiki
  • Enactors page: "important note" under Preference Map should be formally styles as a note Filed in FLUID-5838 - Getting issue details... STATUS
  • Panels page: "important note" under Preference Map should be formally styles as a note Filed in FLUID-5838 - Getting issue details... STATUS
  • Localization page: link to "message resolver" goes straight to wiki, not to a docs placeholder
  • ModelRelay page: a link to "defaults" goes straight into code, which is a bit unexpected. Either a) find an appropriate documentation destination, or b) implement different styling for links to code
    • similarly for "list of available transformations" which links to the gpii wiki
    • similarly for "new notes on change applier"