API design

Jacob Farber jacob.farber at utoronto.ca
Thu Apr 23 19:13:02 UTC 2009

Thanks for the feedback Eli.
I see your point with collapsible content. However I'm thinking everything should be open by default. This might help those who know exactly what they want without tons of scrolling.

As for the glossary + known issues, I think they're useful, but maybe they are too much. Any other ideas?

From: Eli Cochran [mailto:eli at media.berkeley.edu]
Sent: Thursday, April 23, 2009 1:27 PM
To: Jacob Farber
Cc: Eli Cochran; fluid-work List
Subject: Re: API design

I like the overall structure.

I'm not a big fan of collapsable content in a document of this kind. I much prefer links down the page that help me get to the content that I want quickly.

My worry with collapsable content is that something important will be missed.

I'm also not sure that the Glossary or Known Issues are needed on the API page. Unless we see the API page as becoming the main page for the component.

- Eli

On Apr 23, 2009, at 10:07 AM, Jacob Farber wrote:

I would like to share an idea I had for a cleaner, more readable and useable API page layout. I have attached a pdf mockup of what a sample might look like - even though some of the data is real, it's just filler.

There are a few things I would like to emphasize from this concept:
*         Almost all categories are collapsible, enabling a customized reading experience
*         Overview meta data is stored at the top with a  contextualized help link (?)
*         JIRA issues for the code in question are quickly accessible
*         There is a Glossary of terms unique to Infusion and the specific content of the page. Some are unique to the framework, others might just be explanations (in this mockup the [Selector] link would point to a glossary definition saying something like "type Selector = String, jQuery Object, Element, or Function returning an Element or jQuery Object")
*         Color coding
*         Explicitly obvious nested structures

These ideas are just conceptual. Implementation is an entirely different concern.
This is a very rough draft, so all feedback is very welcome!


<C:\Documents and Settings\Jacob\Desktop\docs.pdf>
fluid-work mailing list - fluid-work at fluidproject.org<mailto:fluid-work at fluidproject.org>
To unsubscribe, change settings or access archives,
see http://fluidproject.org/mailman/listinfo/fluid-work

. . . . . . . . . . .  .  .   .    .      .         .              .                     .

Eli Cochran
user interaction developer
ETS, UC Berkeley

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.idrc.ocad.ca/pipermail/fluid-work/attachments/20090423/fbd475dd/attachment.htm>

More information about the fluid-work mailing list