bwo Restructuring Prosposal

This is a proposal for restructuring the bitweaver website and documentation

Created by: Will, Last modification: 02 Aug 2006 (20:17 UTC) by mlpvolt

Documenting BW and bw.o Site Restructuring Proposal


CONCEPT: I propose to undertake some leadership of enhancing the marketing of BW and expanding the developer base. This would be achieved through two non-trivial programs:

  1. Restructure the bw.o site
  2. Creating documentation for BW, such that developers, admins and end users can fully utilize all the core services of Liberty and the Kernel.

I see the restructuring of bw.o as part of and necessary to enhancing the documentation of BW, as it is my observation that while there is much good documentation on the site, it is not easy to find, and the relationships between documents are not easy to grasp.

Specifics of my bw.o site restructuring proposal follow this introduction.

(Will)


Documentation


Using the "wiki method": The most important step to achieving good documentation by wiki not answering documentation type questions email or IRC. This "tough love" practice serves the developers well because they will only have to answer questions once, and as a courtesy in return for having questions answered the questioners should refactor the developer's (likely hurried) answers using the style guide. This approach leaves proper documentation for the next person that comes along with the same question.

Ultimately this kind of "user training" will relieve pressure on the core BW developers to do all the work.

Having a coherrent decision making method for editorial purposes, and a well planned structure to the document, complete with a style guide.

The documentation road map will be a prioritized list of items to complete. Here is a preliminary proposed high level list of prioritized goals:

  • Restructuring bw.o
  • Redesigning the bw.o home page
  • Designing a Developer Gateway
  • Designing a Documentation Gateway
  • Developing Theme tutorials and Package tutorials for R2
(goals within these shall roughly follow the tree structure you will find below)
  • Updating Existing Documentation for R2
  • Developing Documentation for most important APIs

Note: The current API documentation is excellent for highly skilled developers and those accustom to this type of documentation, but I propose that some simplified/structured documentation of the key APIs would go a long toward helping those new to BW. As an example see the way Google documents its APIs. This will probably naturally evolve from the package tutorials.

Site Restructuring Summary


CONCEPT: The main concept is to
a) simplify the design and layout of bw.o - providing more white space and visual structure to the content.
b)target content for the two basic types of visitors Developers and non-developers (end users and site administrators)

  • Site administrators and end-users
  • Developer Section

Each one of these would have its own landing page specifically to target its unique audience.

In addition, a special section of Help Pages, which are exported with all downloaded copies of bitweaver - targeted at end users.

Support and Documentation could be thought of as fourth and fifth sections, and should each have their own landing pages. But I propose to basically structure the deeper content for these relative to Developers and Admins/Designers, so they are not really their own section.

Each Section is described in more detail below.
These are the Sections you will find:

  • Home Page Summary
  • Admin/Designer Section Organizational Tree
  • Developer Section Landing Page Summary
  • Admin/Designer Section Organizational Tree
  • Documentation Section Summary
  • Demo Section Summary


Home Page Summary

CONCEPT: Model Home Page on the websites of similar products using large bold graphics and far fewer options than currently on bw.o. The Homepage also serves as the gateway for admin/designers non-developer types.

MODEL EXAMPLES:
http://www.rubyonrails.org/
http://www.sixapart.com/movabletype/
http://drupal.org/
http://gallery.menalto.com/
http://www.joomla.org/

PROPOSED LAYOUT:
TOP NAVIGATION (site wide):
Overview (Home)
Downloads
Support
Documentation
Developers (alt:Community)
Demo

TOP BLOCK:
Bitweaver Summary Statement
Bullets:
CMS Features
Development Platform
Case Studies
Screen Shots
Latest Release: 1.3.1

BODY BLOCK:
Homepage Type Articles Feed

RIGHT MENU:
(use to highlight cool things, these are just ideas)
Extend Your BW Install With Optional Modules
Easy Theme Your BW Install
Developers Learn What the BW Core Can Do For You

ADDITIONAL CLARIFICATIONS:
Remove Current Top Bar Menu (Site wide change)
Remove Left Menu
Change Content of Right Menu as above and remove all Latest Page Updates, Who's On, Etc

Limit Homepage News Articles to General News, Package Releases/Updates, Security Announcements, Case Studies

Release announcements would be part of main graphics and replace other release announcements. Old release announcements would not remain on the home page. Developer centric news would post only on dev.bitweaver.org. Alternatively developer centric news could be included on the home page but recommended that it be in its own news column.

ALL Bitweaver Package Features, as currently shown on bw.o, would instead be shown on an exclusively Demo site, maybe at: demo.bw.o This would remove a lot extra features from the home page and bw.o that can be distractions to people trying to find key information and learn about the BW product.

VISUAL HOME PAGE SUMMARY (roughly speaking):
| -top nav options- |
| | |
| Bitweaver Graphic | Current |
| and Key Features/Bullet Points | Release |
| | Info |
| | |
| |--------------|
| | |
|-------------------------------------| Other |
| | Promo |
| News | Stuff |
| Feed | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |

Admin/Designer Section Organizational Tree

(These pages would be accessible through a combination of the bw.o homepage, support, and documentation landing page)

BW Features
Overview
Included Packages
Optional Packages
Plugins
Administration
User Management
- all other feature documentation happens on package pages
Installing
Requirements
Download (Do NOT redirect to SourceForge)
Upgrade
Install
- include mention of files need to create if not installing from CVS
Configure (maybe?)
Customizing Graphics (Themes)
Overview
CSS & XHTML
Smarty
The Themes Directory
Per Package Rules (if any)
Package A
Package B
Included Themes
Download Themes
Tutorials (same as below)
Tutorials
FAQ
- list questions up top and then provide explanations.
Support
Forum
IRC

Developer Section Summary

Developer Section Landing Page Summary

CONCEPT: A special landing page for developers would be created to provide a more targeted gateway for them. Many of the menu features currently on the bw.o homepage would move here. The Developer homepage, maybe at dev.bw.o, would provide a fast entry point for developers to connect to the community, to get developer centric news about BW, and quickly find more complex documentation.

TOP BLOCK:
Summary of BW Framework and Core Services, something like the liberty and kernel package pages combined.
Bullets:
(these bullets closely mirror the developer section of the Documentation landing page)
More Details About Why To Develop Using BW
Packages
Documentation and APIs
Tutorials
Development Road Map
Documentation Project
Contributing Code
Coding Standards
Bounties
Forum
IRC
Report a Bug
Footnote: mention Admin/Designer/User Section, for those who may have come to the wrong section

BODY BLOCK:
Developer Centric Type Articles Feed, including selected articles from Personal BW Developer Columns/Blogs (or this might be good in the right menu)

RIGHT MENU:
Login
Updated Wiki Pages
Recent Forum Posts
Who's On
etc

Developer Section Organizational Tree

Framework and Core Services
APIs
Core Kernel and Liberty APIs
Basic Package APIs (Store Expunge List etc)
Comments
History
Security
Commerce (?)
(?)
phpDocumentor
Tutorials (same as below)
Database Tables
Tutorials
Creating a Package
- can 90% of all documentation/tutorials revolve around creating a package?
Schema
Basics: Store, Expunge, List etc
Commenting Your Code
Extending Content
Adding Comments
Adding History
Adding Permissions
Adding Search Indexing
Caching
Templates
Layout Components
Using Smarty
Dynamic Data
Loops
Custom Values
Custom HTML tag properties
Custom HEAD content
Plugins
Integrating Other Apps as a Package
- phpBB example
All Other Tutorials
Road Map
Goals (call to action)
Kernel & Liberty
Packages
Transitioning from Tikiwiki
Progress Reports
Developer Blog Post Includes
Change Log (APIs and Schema)
Bounties
Documentation Project (revamped as call to action on this project with explicit road map)
BW Developer Columns/Blogs
Progress Reports
Forum
Report a Bug
Contributing
About CVS
Process
Coding Standards
Forum
IRC
Package Summaries

Documentation Section Summary

CONCEPT: All Documentation would be accessible through a Documentation Landing Page, which would basically be comprised of two side by side lists. One Section for Admins and Designers the other for Developers. The options in each list would match there respective tree structures as presented above. In other words, the Documentation section would be conceptually broken into two parts. Documentation for site admins/site designers, and documentation for developers.

The current Documentation model suffers from a couple problems:
  • There is no well organized gateway to the documentation
Currently the site uses the Pigeonholes package as a substitute for a gateway. It is moderately navigable, which speaks volumes for the Pigeonholes package! However, sub-category pages are hidden and there are inherent limitations to a tree-structure presentation model, notably when things have not been Categorized well, or at all. The system relies on Categorization of content for it to appear at all as an option, and there is no way to differentiate between good documentation and documentation that is in progress or poorly crafted.

A hand crafted, selected documentation gateway would bring focus to many of the good resources on the site, by organizing the content in a humanistic way. Meanwhile partially complete documentation would remain accessible through the categorization system and through a Documentation Project page. This would make it easy to find for those developing documentation, but out of sight to those evaluating BW or looking for reliable documentation.

  • The naming of pages is awkward and inconsistent
A renaming of pages is recommended focusing on replacing Camel Case names with spaced names for normal reading.

I think it is illuminating to compare the tree structures presented above to the current way documentation is navigated on bw.o org, and compare the current names of pages. Here is a quick cataloging of what and how I found documentation on bw.o:

/*Available in the menus of the home page*/
Download bitweaver (Directs to Source Forge)
bitweaverRequirements
InstallbitweaverDoc
InstallUnderSafeMode
bitweaverUpgrade

Developers FAQ
bitweaverFAQ
RecentChanges
bitweaver Documentation Project
Sample Package
Translation Tutorial
ReleaseOneChangelog
Technical_Documentation

bitweaverFeatures

/* items only accessible through categorization system, mostly under Technical Documentation */
bitweaverOverview
MoreDeveloperDocumentation
APIDocumentation (contains commenting instructions)
bitweaverCVS
bitweaverPerformance
CodingGuidelines
CreatingServices
CssSchema
Integration Tutorial
Package Maintainer Teams
PortingTikiWikiPackages
PrototypeAjaxObject
PrototypeReference
SamplePackage
SearchPackageDevNotes
TUTORIAL - Displaying Icons ONLY to AUTHORS of the page
Tutorial - Liberty Plugins
Tutorial - Liberty Plugins II
Users Doc

Demo Section Summary

CONCEPT: ALL Bitweaver Package Features, as currently shown on bw.o, would instead be shown on an exclusively Demo site, maybe at: demo.bw.o This would remove a lot extra features from bw.o that can be distractions to people trying to find key information and learn about the BW product.

Other Recommended Changes

These are observations I am making as I am going through the site and organizing this Documentation page. They are suggestions. -Will

These two would greatly reduce the cluttered look of the site:
  • Turn off Stars from wiki pages
  • Display page change data only to registered users

Turn off Comments on Wiki Pages - or make it a click to see them. Comments make them look unofficial and add clutter.

Title Differentiation needs improvement. There needs to be more noticible differences between page titles and in-line H1s, and between H1, H2, H3, H4. Recommend making page titles bigger, and changing the color of inline H1, H2, H3, H4, including different colors or tint or weights for each. Also scale differences should probably be greater. Right now it is hard to create distinctions between sections and subsections.