Section 7.4. Accelerating Learning


7.4. Accelerating Learning

The productization described so far satisfies most beginner and intermediate users' needs. But as use of the software grows, more users of all types will arrive and intermediates will grow to the expert level. Other projects will also start using the software for purposes that were not originally anticipated. All of this happens late in a project's life cycle and much more slowly than the initial arrival of beginners. But open source projects can increase adoption further by providing productization designed to serve the needs of expert and advanced users.

7.4.1. Sample Code

Intermediate users require sample code for managing the sort of templating and simple scripting they engage in. Expert- and advanced-level users require sample code that shows how to use the APIs that allow other programs to invoke the functionality of another piece of software. Generally, the more sample code there is, the better. Once a project provides an area for sample code and support for community collaboration around it, users tend to provide more than enough samples.

7.4.2. API Documentation

While sample code is a good way to start supporting developers, open source projects should proceed to the next stage and perform actual documentation. A good first document is a catalog of all APIs available to programmers and a basic tutorial on how they can be used. Well-commented sample code is a great help, but just a few pages that describe the general idea of each API and the different subroutines or services that can be invoked can save a programmer hours of time.

7.4.3. Architecture Documentation

At the expert and advanced levels, the problems get harder. Instead of trying to configure or administer a program, developers are generally asking deeper questions about how they can extend an open source project to solve a new problem or integrate it into another program. Users at this level frequently are able to understand quickly what a project is all about by reading the code. A project can save them time and encourage participation and adoption by providing a high level of architectural documentation. Such documentation should cover the design principles used in the software and the structure of the program's components or modules. Frequently, such documentation lacks an overview and dives right into the details of APIs. Apache.org has a good example of architectural documentation under the documentation section of the Apache project (http://httpd.apache.org/docs-2.1/).

7.4.4. Guide to Embedded Components

Another useful sort of expert and advanced documentation is a guide to how an open source project uses other open source projects that are included as components. Many open source projects come with a list of other open source that must be installed. Documentation of what each embedded open source component does in an application can help to speed the learning process. The decisions that the core development team made in selecting a component can quickly help other expert and advanced users make sense of how an open source project is constructed.



Open Source for the Enterprise
Open Source for the Enterprise
ISBN: 596101198
EAN: N/A
Year: 2003
Pages: 134

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net