History of bwo Restructuring Prosposal
Version 1 | Current version | |
---|---|---|
NOTE: some of the formatting of this page is a little messed up because it was not written for wiki, to see it clean, click edit and copy the raw text and paste it into a text editor. -Will Documenting BW and bw.o Site Restructuring Proposal1. Restructure bw.o 2. Enhancing the documentation of BW to a highly reliable level, such that developers new to BW can easily build out a complex package utilizing 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. The Documenting of BW shall be taken up as a high profile project on bw.o and evangelized to the BW small but dedicated developer community. This means raising documenting BW to the level of a call to action. This project will have a clear road map, goals will be set, needs will be clearly defined and prioritized, update reports given, all done with the intent to encourage other developers in the BW ring to help out. As the ultimate goal of this project is to relieve pressure on the core BW developers, I am seeking your participation as evangelists of this project. The documentation road map will be a prioritized list of items to complete. Here is a preliminary proposed high level list of prioritized goals:
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
Each one of these would have its own landing page specifically to target its unique audience. 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. These are the Sections you will find:
Home Page SummaryMODEL 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 TreeBW 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 SummaryDeveloper Section Landing Page SummaryTOP 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 TreeAPIs 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 SummaryThe current Documentation model suffers from a couple problems:
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.
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 | Documenting BW and bw.o Site Restructuring ProposalCONCEPT: 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:
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) DocumentationUsing 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:
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 SummaryCONCEPT: 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)
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. These are the Sections you will find:
Home Page SummaryMODEL 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 TreeBW 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 SummaryDeveloper Section Landing Page SummaryTOP 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 TreeAPIs 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 SummaryThe current Documentation model suffers from a couple problems:
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.
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 SummaryOther Recommended ChangesThese are observations I am making as I am going through the site and organizing this Documentation page. They are suggestions. -WillThese two would greatly reduce the cluttered look of the site:
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. |