On Wed, Feb 3, 2010 at 11:01 AM, C. Michael Pilato <cmpil...@collab.net> wrote:
> A pitfall that I'd like us to avoid is the one that assumes that every piece
> of information of interested must be only a single click away. That might
> have been true in 1994 because of typical network speeds. But that's not
> reality today. The site as it sits today is laid out with what I think is a
> reasonable assumption: that visitors will enter through the home page and
> are visiting with intent. I don't tend to visit a software project's
> website and just poke around to see what I can see. I come looking for
> docs, or for help/support, or for a new release, or for something else. I
> believe others do the same. So it's okay if our homepage and left-nav serve
> only the purpose of triaging site visitors based on what they are looking
> for in general, and then other pages serve up the specifics. These are
> (some of) the design philosophies behind what you see today.
I grok that - but, I also think it's useful (as was my use case
yesterday) when that you *know* there's something on the site that you
can find it with a minimum of fuss. I spent more time searching for
that darn HACKING^Wcommunity guide than it did for me to review the
patch or write the email pointing Daniel at the link. I knew the text
was there, but I simply couldn't find it to save my life - that led to
my frustration...HACKING is simply a part of our community. =P
> I really, really don't want to put any links in the left-nav proper to
> destinations that don't carry that menu. I cannot stress this enough. A
> site visitor should reasonably expect that the menu that helps him or her
> get around the site also keeps them "on the (branded) site". And as I've
> mentioned in other discussions, HACKING is far too lengthy a document to be
> considered "part of the website", in much the same way that "Version Control
> with Subversion" is.
My hunch is that HACKING probably ought to be split up rather than
kept as a monolithic big guide. But, if we treat it separately, isn't
that a reason to expressly link to it? What if we created "another"
sub-site for community with a different template? We could then slice
HACKING up into a proper "mini-site" - and refer to it with a link on
the side-bar off svn.a.o. =P
> That said, I agree that the Documentation page is not the best way to slice
> that information. I totally "get" how the most common class of site visitor
> would assume a set of contents there that aren't. So I like some the
> suggestions here.
>
> Would could physically move the Release Notes section into a new
> docs/release-notes/index.html, expand that simple list of links a bit to
> mention (in a non-detailed way) the "big highlights" of each release ("file
> locking", "merge tracking", "tree conflicts detection", etc.), and link to
> it in the left-nav in the manner you describe.
I'm happy to take a pass at drafting that.
> I'd suggest moving the C API docs, JavaHL doc, and HACKING link to the (new)
> Developer Resources page.
>
> I'd also suggest simply renaming the "Getting Involved" link to just
> "Contributing" (as opposed to adding another separate link for "Contributing
> Code"). As you can tell by the physical name of that page
> (contributing.html), that's the title I really think it should have anyway.
The reason for the name change I suggested was that I think there's a
fuzzy layer between "Community" and "Developer Resources". I don't
think the extra indirection buys us much - the audience is much the
same. In the minimalist world, lists and issue trackers wouldn't be
in the sidebar - so there's a line I think we need to explore here.
> That really only leaves the "Version Control with Subversion" link to deal
> with. I have a semi-obnoxious suggestion here that satisfies my strong
> left-nav opinions: put a thumbnail of the book at the bottom of the
> left-nav menu which links to svnbook.org.
If it is to serve as the main docco link on our site, it should
probably be featured a bit more prominently than at the bottom of the
left-nav menu. I would think it'd be a very popular link. =)
Oh, BTW, I know you're going to hate me, but ASF policy is that every
project site has a reasonably-prominent link to:
http://www.apache.org/foundation/thanks.html
(It can be either "Thanks" or "Sponsors" or something related to that
phraseology. The left-nav would be perfect for it. *grin* Maybe we
can get away with just including it in the "disclaimer" text, but I
think it'd be nice to be a bit more prominent than that.)
*duck* -- justin
