Project35 Design Manual - for Developers

We've worked with various developers in the past and have found it to be enormously beneficial. We've decided that instead of hiding away our code as some people choose to, we are very open about how it all works. If you think you'd like to get involved in some aspect, let us know. We would ask that you have a look at the way the code is formatted for things such as variable naming and layout before you do though. We would expect you to use the coding conventions we have adopted to ensure a high level of consistency in the code base. You would also be responsible for the initial testing of any modules and we would expect you to provide documentation for your work. It might sound like a lot but we have found that most developers have no problems with this approach, especially if they are using the product themselves.

Some of the aspects of the development section may be a little long so we have divided them into sections linked to from the list below.

• Architecture
• Extending the Architecture
• Creating Service Plugins
• Java Docs

Project philosophy towards development

The project began as an effort to provide free software tools that could help support activities in the developing world. The main motivation for doing the work came from humanitarian rather than commercial interests. We already earn a living from other software jobs we do. One of our main development goals is to make a small suite of robust tools that do simple things well. The other main development goal is to produce software that people can adapt without being forced to rely on us. Our experience is that open-source software has the greatest appeal when the people who use it no longer have to depend on the people who made it. We want people who use this to make it their own.

Normally it is difficult to maintain a large, complex software application without a significant and continuous source of resources. However, there are aspects of our development philosophy that make it possible for us to manage this project:

• The software is already mature.
  
  Project35 adapted software applications that had been developed over a period of about five years. We do not anticipate any great changes in the code based on what we intend the software to do.
  
  
• Support a minimum number of features.
  
  Each feature in an application can require significant resources to build, test, and document. As well, if end-users have to navigate through too many features, they will begin not to use them. Consider that many features in well-established applications never get used and make the application more complicated to use.
  
  
• Invest in maintenance, not new features.
  
  Our own resources for developing the software are limited, so we have to decide whether we want to focus on the development of new features or the maintenance of existing ones. The Project35 team feels that the creation of many new features is only possible if we can attract a larger developer team with a wide range of user requirements. We will only attract new developers if they feel that they can adapt stable code that works and that is easy to understand.
  
  
• Don't impose the software.
  
  If the software suits your needs, please use it. Otherwise, please don't! Because we're not interested in selling you the software, we're not interested in investing our energies trying to show that the software can be used for purposes it was not originally designed to support.

Perhaps the most important aspect of our philosophy is that we assume projects or requrements may outgrow the software. Project35 has well defined development goals and we know when we would like to stop feature development. We want to rapidly stabilise the code base for two reasons. First, we want developers to feel confident that the software won’t change much for the duration of their own projects. Second, we want to support having the learning materials written in multiple languages.

Eventually, your needs may go beyond what the software supports. In these cases, you can either make your own version of it or reduce your dependence on it. To help you stop using the application, we have designed Project35 to support different levels of “buy-in”.

• Use Project35 to prototype applications.
  
  The data entry forms that are generated by Project35 are based on the concepts you define in your XML schema. When you change the schema, it takes very little work to generate forms that reflect the new changes. Our experience has been that many groups would only use the software to get an idea of what they would want to be supported in a data entry tool. Project35 does not have to be that tool! The generation of the forms allows end-users to make suggestions without them having to understanding the abstractions of the underlying data model that drives the application. In effect, the end-users validate your data model before you decide on spending months creating your own data entry tool from scratch.

  In Project35 the schema concepts correspond to records and fields you would see in an electronic form. You can use a Configuration Tool to associate other properties with those form concepts. The tool can use both the schema and the configuration options you set to produce a functional specification of what the data entry tool should do. The specification is an HTML document that you can print out and give to people at meetings. Your groups can refer to the document when they are discussing what the prototype should support.

  At the end of this prototyping phase, you can use the prototype and the functional specifications to guide the development of a custom built data entry application. If you like using Project35, you can continue to use it as a production line tool.

• Use Project35 for production.
  
  If you decide you want to use Project35 as your production tool, you may need to make software plugins. The download should include tutorials for making your own plugins. We hope that eventually a community of developers will provide other examples you can use.

  There is also one other important example that developers can use: the Configuration Tool. The forms for the Project35 Configuration Tool are generated from a schema that defines configuration options. The tool supports a number of plugins which you will use when you are building your prototype. If you want to know how those features work, you can inspect the code that is part of the main code base.

  You can use Project35 as a standalone application or as a component that is launched from another application. You can also generate forms to suit the screens of either a desktop monitor or a PC Tablet screen.

• Use Project35 for production, then stop using it.
  
  Suppose you have been using Project35 for a few years and you want to stop using it. You may have a number of legacy data files ending with the extension “.PDZ”. You can use the tool to export a .PDZ file to an XML file which has a data format that is used throughout the IT industry.

  You can also develop programs for extracting information from the file. Each .PDZ file is actually a ZIP file that contains at least two small XML files – one that contains just the form data and another that contains other file information. You can open a .PDZ file with a tool such as WinZip and take the information you want.

• Use other existing tools.
  
  Project35 is not the only tool that uses an XML schema to generate forms - other applications do this task as well. We think our software is much simpler than most but also that it can support more sophisticated features for validation and form mark-up. Also – our software is free!