-
Notifications
You must be signed in to change notification settings - Fork 168
Design Doc: SiteMesh Website
This describes plans for the SiteMesh3 website.
The hosted infrastructure is divided into 2 categories:
- User facing: Simple, understandable resources for end users (website, downloads, documentation, community, announcements)
- Developer facing: Tools to support the SiteMesh team and contributors (source control, issue tracking, wiki…)
There will intentionally be a clear divide between these two as they are for very different audiences.
This document focusses on the user facing infrastructure only (see Design Doc: Developer Infrastructure for the other side of this).
Keep it simple!
There are a few high level components:
- Website
- Documentation
- Downloads
- Community
- Announcements
The website’s primary purpose is to introduce SiteMesh to curious potential users. It should be clean, to the point and not overwhelming.
It will not act as a developer team hub as this can be confusing for the majority of users who are not on the team. At most there may be a small link to the developer hub.
Suggested content for the website:
- What is SiteMesh?
- Download
- Getting started guide
- SiteMesh vs Includes
- Link to full documentation (separate to the website)
- Link to user mailing list
- A very simple home page, with a high level overview of SiteMesh, links to relevant sections and recent announcements
Good example sites:
- http://rubyonrails.org/
- http://cukes.info/
- http://wtr.rubyforge.org/
- http://www.grails.org/
- http://cappuccino.org/
- http://www.mochikit.com/
- http://www.eucalyptus.com/
- http://ramaze.net/
- http://neo4j.org/
One of SiteMesh2’s biggest weaknesses was the documentation. While there was a fair amount of content, it was not structured in a way that was easy for users to follow.
The types of users the docs should cater for:
- New and trying to get started
- Migrating from SiteMesh 2
- Exploring features and ideas for things that can be done
- Trying to find the answer to a particular question
- Deep diving into a particular topic
In each case, a clear trail should be provided to guide the user through the docs without them getting lost, overwhelmed or distracted.
Other guiding principles:
- Docs should be relatively short (reading time: 1-5 mins)
- Docs should have a clear and short summary at the top, stating what will be learned by reading it
- If the doc is part of a logical series of docs, it should contain clear links to the next/prev doc in the series
- Otherwise, the doc should have links to relevant related docs
- Favor example code, short bullet lists or diagrams over lengthy paragraphs of text
Proposed structured:
- Introduction path (new users):
- A short series of tutorials that help them understand SM, start using it and get a bit more info on the core features and usage patterns.
- Upon completing the series, the user should have the knowledge to use SM effectively
- Each tutorial in the series should build upon the previous one, but if a user does not complete the series they should still have enough information to start doing something with SM
- Migration path (SM2 users):
- Similar to the introduction path, but more of a focus on what’s changed
- May reuse many of the tutorials of the introduction path
- Patterns (hmmm, need a more descriptive term):
- Some common types of SM sites
- How to assemble/structure content/decorators
- Examples: Simple site, deep nav structure, CMS system, portal, nested layouts…
- Cookbook:
- List of short ‘how do I…’ style articles for various scenario
- Should be easy to explore and provide inspiration for things users can do
- Reference:
- Tag reference, configuration, etc
- Simplified JavaDoc – just for the core APIs that users should care about
- Advanced deep dives:
- For those that want to get down and dirty with SM (e.g. how the tag processor works, or building your own filter pipeline)
- Probably much longer articles for more advanced users
Finally, I would like the latest documentation to be linked from the main SiteMesh website, but also have the documentation included in the download distribution so users can reference it offline.
The website front page should clearly indicate the latest version number (and release date) with a direct link to download. Additionally, we should link to a directory where historical versions can be downloaded.
To keep things simple for users, there will only be 2 choices for downloads:
- sitemesh.jar: Just the standalone library (small download)
- sitemesh.zip: Full binary distribution including: library jar, source jar, docs, examples
The example and blank war downloads that were packaged for SM2 will no longer be supported (the getting started guide and full distribution should be sufficient)
A buildable source distribution shall not be available from the user facing website. However the developer hub may contain details on this.
Additionally, appropriate files will be published to the Maven repository to support Maven/Ivy users (with instructions).
The community will be backed by a single mailing list (sitemesh-users). The site shall contain instructions for sub/unsub, posting and a web view.
Measures need to be taken to protect from spam, which plagues the SM2 mailing list on Java.net.
To keep things simple, that will be it. No IRC channel, wiki, bug tracker, etc. These tools may be used by developers, but we want to shield the end users from it (the more hands on user can always go to the developer hub).
When important announcements are made (typically new releases, but maybe other things such as promoting tutorials), they will go to:
- an annoucements mailing list (that anyone can subscribe to, but only the dev team can post to)
- the front page of the website
- an RSS feed
The website will be hosted on Google AppEngine (reliable, scalable, easy to use and supports Java web-apps). It will be on the domain www.sitemesh.org. The old http://opensymphony.com/sitemesh URL will redirect to the new site once ready.
The documentation will be a set of static content, available both on the website and distributed in the SiteMesh download.
A page detailing all the downloads will be part of the website, but the actual download files will most likely be hosted as part of the Design Doc: Developer Infrastructure.
The community will be hosted by Google Groups (reliable, well managed, spam protection, good features, and simple UI).
- sitemesh.org/.net domain transfered.
- Shell of a site built (sitemesh-website package).
- Logo designed.
- Basic documentation started
- Deployed to AppEngine: http://docs.sitemesh.org/