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.



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.


TOP NAVIGATION (site wide):
Overview (Home)
Developers (alt:Community)

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

Homepage Type Articles Feed

(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

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 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: 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
Included Packages
Optional Packages
User Management
- all other feature documentation happens on package pages
Download (Do NOT redirect to SourceForge)
- include mention of files need to create if not installing from CVS
Configure (maybe?)
Customizing Graphics (Themes)
The Themes Directory
Per Package Rules (if any)
Package A
Package B
Included Themes
Download Themes
Tutorials (same as below)
- list questions up top and then provide explanations.

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, 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.

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

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

Updated Wiki Pages
Recent Forum Posts
Who's On

Developer Section Organizational Tree

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

Developers FAQ
bitweaver Documentation Project
Sample Package
Translation Tutorial


/* items only accessible through categorization system, mostly under Technical Documentation */
APIDocumentation (contains commenting instructions)
Integration Tutorial
Package Maintainer Teams
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: 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.