Hello everyone,
As many of you know, we spent some time
on Friday working on the web site at Almaden. We didn't get as far
as we would've liked to have (didn't even touch the wiki), but we make
some changes to the new front page and tried to start some precedents on
how component pages should be structured.
I apologize for getting this email out
so late, I intended to send it on Saturday for discussion today during
the call. We can defer the discussion to next week if you all would
prefer to have time for review.
The Home Page
http://www.eclipse.org/ohf/index2.php
It's largely like the previously one
with some reorganization of styles and reordering of links. The most
important change is higlighting the components - and the reason for my
email on Friday. Previously this was a bunch of acronyms - which
was absolutely useless to anyone who isn't a committer. We've now
brought the components to be the centerpiece of the main page and included
a one sentence description of WHAT each is. There is still some
outstanding discussion on where the component list should be - should it
be the top item, between the four boxes, or below the four boxes. Right
now, only the top two or three components make it "above the fold"
on browsers running 1024x768 resolution. Additionally, if you
do not like the one sentence description of your component, please email
me with a new one. These were largely inserted as placeholders,
so please update if you wish.
Home Page "What's New"
box
Another thing we weren't sure how to
handle is the "What's New" box. Ideally, this is the only
thing that will change with any regularity on the front page - thus it's
something that should be highlighted and, you know, actually updated. My
recommendation is that we tie it to the OHF-DEV blog. Because the
web site is PHP-driven, it would be relatively painless to use an RSS client
to aggregate the top 3 or 4 titles of blog posts on OHF-DEV as our "What's
New" box. This gives incentive to posting to OHF-DEV (open to
all committers btw) and keeps the OHF front page fresh without having to
update multiple things. Depending on currency of the titles, it
might be worthy to bump that box up to position 1 on the page... not right
now though. Additionally, we can also have a "news" page
that aggregates the top 10 or 15 titles from all OHF blogs.
OHF "Getting Started" page
http://www.eclipse.org/ohf/gettingstarted.php
We decided that it is important to have
a unified place to start with OHF - and a "Getting Started" page
is a good place. Getting Started is a complicated idea in OHF, because
most of the components have different requirements and dependencies that
are not shared. However, there are a few things in common (it's in
Java and we encourage you to use Eclipse  and we decided that it's good
to at least give a place where everyone should initially go. From
the getting started page, then you get linked to each component's Getting
Started page (see below). We did not finished developing the content
for this page just yet, but it's definitely a work in progress and any
shared / project-wide ideas to help get users giong would be appreciated.
Component / Subcomponent Home Pages
http://www.eclipse.org/ohf/components/component_name/index.php
and http://www.eclipse.org/ohf/components/component_name/subcomponent_name.php
A lot of the work on Friday was spent
discussing the component pages and how to handle content there.
As a starting point for now, we have built a basic framework for handling
component pages and included a template for new components.
On each Component Main Page, we decided
on a four box layout:
* About
* Project Status
* Getting Started
* Resources
About
A one to two paragraph introductory
explanation of the idea behind the component and a quick breakdown of the
logical subcomponents (in this case, subcomponents would be XDS, PIX, PDQ
in the IHE component; SAT and DK for SODA, etc).
Project Status
A clear and concise explanation of the
project's current build availablity / release status. An example
would be:
Stable
Build: 0.2.0 Milestone 2 (IHE 2006-2007 profiles)
Development
Build: 0.3.0 Alpha (IHE 2007-2008
profiles)
You could also link to your nightly
builds from this if you wish. I'd like to explore a little more how
this can be useful.
Getting Started
Very quick comments on how to get started
with your project. Could include basic requirements (Java 5, Eclipse
3.2/3.3, etc). Intention is to brief the user and then link to the
component's getting started page for the nitty gritty (see below)
Resources
Links to resources for the project.
Can be just about anything you want, but don't get out of control.
For the subcomponent front pages, we
decided to stick with About and Resources.
Beyond that, content should be added
as you wish (though see the "Outstanding Issues" section at the
bottom)
Component Getting Started page
http://www.eclipse.org/ohf/components/component_name/gettingstarted.php
Perhaps the most important page for
each component - and on the entire site. This should be the catch-all
starting point for users of your component. It should contain the
following sections:
* Requirements
* Download
* Install
* Configure
* Test (optional)
You can break these out into individual
pages if you'd like. Obviously some of those bullets won't be required
for each component and it's kind of difficult to explain an install for
some components (how exactly do you INSTALL and IHE plug-in?)... but that's
what those boxes are for. Explain how to use your component. A
lot of users will come to the site looking for a self-extracting InstallShield
.exe that they download and double click on. For components that
don't fit into this paradigm, it's extremely important that the user understands
just what they're dealing with.
Outstanding Issues
While we did make some good progress
on Friday, there's still A LOT left unresolved.
1. The Wiki
It's a complete and utter mess. We
will be spending another day in a couple weeks solely focusing on the wiki.
Until then, I encourage owners of pages to start putting together
some better ideas on how to handle content there.... and what should be
there... which leads to:
2. Use of the web site vs. use
of the wiki (or formal vs. informal documentation)
We need to come up with a point of demarcation
to distinguish what goes on the wiki and what goes on the web site. A
good place would be "formal vs. informal documentation", but
that leads to greater questions. I'm pretty anal on keeping web site
content uniform for a user's experience, so that's why I prefer to keep
what's absolutely necessary to get a user started on the OHF web site and
not have people bouncing back and forth between the wiki. In my opinion,
if the audience of the content fits in the "USER" category, it
goes on the web site and if it's in the "DEVELOPER" category,
then consider the wiki. It warrants discussion on a decision though...
3. Actual format of formal documentation
Right now documentation exists in 3
or 4 formats: Javadoc, PDF/Word, pure HTML, and Wiki. Some
of it's browsable, some is contained in ZIP files or is in CVS. Consistency
should be a factor here, we should take steps to decide on how to be consistent
(maybe this is best to be discussed at a face-to-face meeting).
4. Others that I can't think of
right now......
OK, sorry for the long email. Again,
please review the pages and comment on what you do / do not like. We
still have a ways to go, but these are important first steps to getting
the web site usable and useful for both users and developers of OHF.
Thanks
-Matt Davis
Matthew Davis
IBM Almaden Research Center
San Jose, CA
p. 408-927-1029 (t/l 457-1029)
e. mattadav us.ibm.com
|
