Andy Oram
31 January 2009
This document contains a design for the online educational environment described in my article Developing an improved online environment for educating computer users. The design document is available in the following formats:
ODF, 64,468 bytes
Word (DOC), 305,664 bytes
PDF, 816,363 bytes
The purpose of this environment is to help people contribute information to computing projects and to help other people find that information more easily. Each version of this document has a unique filename containing the date of its publication, to allow references to particular versions of the document.
I am not a software architect, so I am ready to hear that there are problems in this design. Please comment on part or all of this document by writing to me at account andyo at domain oreilly.com. You can put your comments in your email or use revision control (change tracking) to show changes and add suggestions, and send me the resulting document.
You can read and comment on each section independently:
This short section shows the purpose of the design and how people are expected to use it. You can offer useful comments on this material without reading the rest. More background is available in the article listed at the start of this document, along with companion pieces at http://www.praxagora.com/community_documentation.
This is the bulk of the document, suggesting a RESTful API that can support the system. It should be read by people with some knowledge of software design.
In order to keep the Use cases section short and focus on the positives, most of the difficulties I've encountered are dumped into this final section. This section should be a hot spot for discussions of the system's viability, and can be read by anyone who wants to look at the potential pitfalls of the system.
Earlier versions of API document in ODF format: August 11, 2008; August 28, 2008; September 10, 2008; September 17, 2008; September 24, 2008; November 28, 2008; December 30, 2008