vozmob technical documentation

As the vozmob platform grows more complex, we need to start building two sets of ‘user manuals’.

The first, and most urgent as we plan to roll out in a couple of months, is the manual for end-users. This needs to document how new users can join, how to use the system, and inform them of issues they ought to be aware of (e.g. privacy). This document needs to be written in straightforward language (or maybe in pictures?), both in English and Spanish.

The second is a manual for systems operators, which will be needed a few months later. This needs to describe how to set up the system, install and manage features. While this is probably meant for more sophisticated readers, it would be best to keep it simple as well. This also needs to be done in English and Spanish.

(we’ll also need to document the social side of things, publish curriculum, etc. but that’s a subject for another post).

Information about how things work (or should work) is currently kept in a variety of ways in a number of places. The two main ones are:

  1. the project wiki at wiki.vozmob.net, with pages like VozMobFeatures
  2. the bug and feature tracking site at dev.vozmob.net, like this discussion about tagging content sent from phones

But there are also tidbits in various other places, which we try to summarize in, or tie to, the two above:

So, the first challenge is to keep everything in synch without too much administrative hassle. The second challenge will be to use all that information to write the two simple manuals, in both English and Spanish (and keep them up-to-date as vozmob evolves).

Any suggestion about how to best organize ourselves to do that? Any pointer to best-practice?

One option might be to identify ‘curators’ for each of these two manuals, who would take on the responsibility to set up the document structure, periodically prod other team members to draft and update the sections that match their competence, and keep the document in good shape. Actually, setting up bilingual duos of curators for each document might be better, with one person from ASC and one from IDEPSCA in each team.

(also see related discussion at http://dev.vozmob.net/issues/show/39)

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s