Infusion documentation plan
antranig.basman at colorado.edu
Fri Apr 17 15:53:08 EDT 2015
Thanks to all for the great work on the Infusion docs. It's great to finally have a proper docs site after
all these years. Thanks to Simon, Anastasia, Jonathan and everyone else who worked on them.
Here are some suggestions for reforming the top-level grouping -
The current split of some material into "Infusion" and others into "API" doesn't make too much sense.
Certainly whatever top-level grouping we have, material such as "ChangeApplier API" should go together with
"Events", "IoC", "Framework API", etc.
I suggest that we have one area called "Infusion" or "Framework" which includes
- everything currently in "Infusion", plus ChangeApplier API, Framework API, DOM Binder API
Another area called "Components" which includes
- everything else currently in API - that is, everything from "Inline Edit" down to "Table of Contents".
I suggest we do away with the top-level name "API" since we don't really believe in having APIs anyway.
We should either put "Preferences Framework" in a top-level grouping of its own, or else at the bottom of
the "Framework" area or the top of the "Components" area to emphasise that it lives at a special level of
abstraction - it is less abstract than all the rest of the "framework", but more abstract than any component.
Styling suggestions - the current top-level categorisation doesn't have a very evident styling. I suggest that
i) The top-level items be moved from the right to the left of the top level pane - especially since we now
have UIO there which clutters that area more.
ii) The active item be given a "tabbed" styling (that is, a background which agrees with the main page
background, and a continuous layout) to emphasise that it is the section that the user is currently in.
The other major styling issues I notice are:
a) The "inline code style" with the rounded rectangle is obtrusive and sometimes overlaps items on the next
line and/or gets line-wrapped. I think we should do away with that and just have a styling based on font/colour
b) The navigation for the left pane should have a "scroll-to" so that the currently selected item is always
visible. For example, currently navigating to
http://docs.fluidproject.org/infusion/development/PreferencesEditor.html has the active item scrolled off
the bottom of the left pane and so the user will become confused about their location.
The styling in general has a nice and clean look and is a vast improvement on anything we have had before :)
More information about the fluid-work