Infusion documentation plan

Antranig Basman 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 :)


Cheers,
Antranig





More information about the fluid-work mailing list