RFC #0002: Reorganize documentation

The documentation needs to be reorganized and split into different chapters, as there are different requirements of knowledge for working with Stubbles depending on which role a user takes.

Overview

Author:Frank Kleine (mikey)
Contributors:-
Created:2008-07-26
Status:accepted
Category:organisational

Rationale

Current documentation mixes informations for users and developers. This needs to be sorted out so that users only get the information they require to build websites with Stubbles and developers find information they require to use Stubbles classes for creating their applications.

Additionally the document creation must be more closely to the code creation, which means it has to be moved from wiki into repository. This will also be useful when different stable releases emerge, as this will allow to have the documentation based on the release instead of having all documentation versions within the same wiki page.

Functionality

Documentation reorganization

The documentation will be split into different parts:

  1. Introduction to Stubbles
  2. Installation and setup
    • The directory layout of Stubbles
    • Configuring the virtual host in Apache
    • Upgrading your Stubbles installation to a new Stubbles version
  3. Creating websites with XML/XSL view engine (frontend producer view)
    • Projects
      • The common project
    • Skin
    • How to create a new page
    • Style sheets
      • General XSL Templates
      • Variant support
  4. Basic Stubbles concepts for developers
    • Using the Stubbles class loader
    • Basic methods available in (nearly) all classes of Stubbles
    • Enum support
    • Runtime modes
      • Error handler
      • Exception handler
    • Extended Reflection API
      • Annotations in Stubbles
      • All available annotations
    • Initializers
  5. The Inversion of Control container
  6. Creating applications based on XML/XSL view engine (developer view)
    • How the XML/XSL view engine works
    • Configuration
      • Registry
      • Processor and interceptors
      • Website Cache
      • Behind the scenes
        • Controller, Processors and Processor resolvers
        • Purpose of the page factory
        • Initializers again
    • Dynamic content with page elements
    • Working with request data
      • Validator
      • Filters
      • Request broker
    • Using the session
    • The response object
    • Pre- and post interceptors
      • Interceptors provided by Stubbles
    • Easy AJAX with JSON-RPC
    • Testing customer experience with variants
  7. Working with XML
    • Creating XML documents with the XMLStreamWriter
    • Creating XML documents with the XMLSerializer
    • Unserializing XML documents into simple data structures
    • Support for RSS feeds
  8. Working with databases
    • Database configuration
    • Connection handling with the connection pool
    • Connection, Statement and Result
    • Criteria
    • Persistence API
      • Entities
        • Annotations for entities
      • Entity manager
        • Behind the scenes
          • Finder
          • Serializer
          • Eraser
      • Setup from entities
  9. Support for command line scripts
    • executor
    • input, output and error stream
  10. Other helpful packages
    • Over the wire
      • Sockets
      • HTTP
      • LDAP
    • String en-/decoder
    • SOAP support
    • Input- and output streams
    • Using the cache component
    • Log 'til you drop: the logging API

Chapters 1-6 are in the sequence one should learn about Stubbles. Chapters 7-10 require only chapter 1, 2 and 4.

Move documentation into repository

In order to better integrate documentation with code development the documentation will be moved into the repository. The already existing folder docs will have a new subfolder manual which contains the documentation related files which build the manual. Format of these files will be docbook, and transformation to HTML (and other formats) will be done with a Phing task.

The manual subfolder will consist of the following subfolders:

  • content - the actual docbook files
  • out - transformed files (i.e. manual as HTML)
  • styles - custom stylesheets for docbook transformation

Security considerations

n/a

Speed impact

n/a

Dependencies

n/a

Related documents

n/a

Comments, changes etc.

  • Added repository and docbook related stuff. (mikey, 2008-07-28)

Back to RFC list