Google Doc Sprint

Google is hosting a ​doc sprint, 17th - 21st October, prior to the 2011 GSoC Summit, to produce or improve documentation for selected GSoC organizations. A proposal for Sahana was accepted, Michael, Shikhar, Leslie, Dominic, and Fran will be attending.

Brain Storming

From Sahana Eden List

I've been giving this some thought, from a developer perspective, looking at building a new module/application (or whatever they are called)... I think that the most important area to highlight would be the model and all the different hooks that can be set there. The requires, represent, onvalidate, onaccept, s3_meta_fields, reusable fields, etc. I believe that these are key ideas for new people to comprehend before developing and I would suggest that some are counter-intuitive for people who have MVC experience so I would certainly avoid any emphasis about this being a MVC framework.

The simple ones above are those that go with the model. The tricky ones -- onvalidate, onaccept -- are ones that are assigned in the model, but which act in the controller. The controller timeline -- what happens when, and where the hooks tie in (like what Dominic had for an earlier version) -- is most helpful in understanding what customizations should go in which callback, and such.

After that I'd be interested in seeing something about the rheader. component tabs and generally how the records link together. Ok, there's a part of the model that would be good to describe -- components and the various ways they can be linked (fk ref, relationship table, 1-1, 1-M, shared components,...)

• AuthS3:
  • additional policies 6+7 (OrgAuth)
  • delegation of permissions
• S3Search extensions (e.g. embeddable widget)
• REST method handler registry
• REST new hooks (ondelete_cascade, onconflict etc).
• Link table support in REST/CRUD
• Virtual fields support
• Synchronization (S3Sync)
• Scheduled tasks (S3Task)
• Two-phase imports (including review UI)

Desired Outputs

Reference Poster

Quick Start Guide

Part of the event will be the production of a "quick start guide". Please add suggestions here for organization and contents.

Wiki Docs for Developers

Generally:

• How things work
• How things are linked together
• Integrate back-end framework with front end interface

There may also be work on the online docs, i.e. this wiki. Please record here any gaps you've encountered in the online docs, or any parts that are out of date, or anything unclear. Of course, you can also fix those things. ;-)

• Developer installation instructions for Mac needed -- Macs are increasingly popular among devs.
• Order of production installation instructions seems inverted -- one must navigate into pages for specific types of web server setup to find parts that cover installation of the actual software, e.g. Web2py, Python and dependencies, Eden.
• Production installation links for Windows Server don't include installation of the actual software.

Wiki Docs for User

• Screen casts are good
• Provide guidance for GCI students to produce more documentation - including simulations
• Useful for:
  • For developers (context)
  • For testers
  • For users (although these will often need to be adapted for specific business processes/context)

Steam-lining Documentation

Is there a way to automatically generate guides & presentation for use in trainings and printing from our wiki content

FOSS for a Better World Guide

Probably not going to be developed at the Doc Sprint, but an idea worth discussing:

• (Humanitarian / Development / Health / Environment)
• This could be a project agnostic guide, probably more aimed at the users of FOSS, rather than the developers.
• Basically it would contain all the information which I wish non-techies understood when I was working with them:
  • Information Management basics
  • Technology Options (Maps, Mobile, SMS)
  • How to specify System/User Requirements
  • IT Project Cycle
  • Usability
  • Training
  • Integrating different systems (XML).
• Just a small book 30-60 pages, easy to digest, pretty diagrams & colors…
• Something I've come across before is: ​http://www.ecbproject.org/GoodEnoughGuide - different topic, but same audience and type of document.