Wednesday, October 13, 2010

Make a web app on your own

As always, I've written this article for myself. It is about how should I approach when I have a website idea, but no motivation to start. I took an inspiration from Craig Larman's book: Applying UML and Patterns 3rd edition. The title sounds like UML book, but its in fact more about doing software right. So where do I start?

Vision and Business Case

This is a high level and terse text document about what I am developing. It should consist of:
  • Problems of stakeholders being solved.
  • Competition of mine.
  • Features of the new system.
  • Other chapters may include: Description of Stakeholders, Users, Goals of Stakeholders, Users, Summary of Benefits, Constraints, Cost and Pricing, Licencing and Installation, ...
Please note that this document will probably not be finished on a first try. It will be revisited after use-case analysis is mostly done. This applies to all following documents. They are just started earlier than others, and are usually not finished before the others start.

Use-case model

This document describes the functional (behavioral) requirements of the system. During inception phase, the names of most use-cases should be known and approximately 10% of use-cases should be analyzed in the detail.

The most detailed use-case specification should contain:
  • Use Case Name started with a verb.
  • Scope- the system under design.
  • Level- either 'user-goal' or 'sub-function'.
  • Primary Actor who calls the system to deliver the service.
  • Preconditions - What must be true on start and worth mentioning?
  • Postconditions - What must be true on the end and worth mentioning?
  • Main success scenario - A typical, unconditionally happy scenario of success.
  • Extensions - Alternative flows.
  • Others: Stakeholders and Interests, Special Requirements, Technology and Data Variations List, Frequency of Occurrence, Miscellaneous, ...
Supplementary specification

Describes other requirements, mostly non-functional. During inception, it is useful to have some idea of the key non-functional requirements that have will have a major impact on the architecture. Following the FURPS+ model, this specification deals with:
  • Functional features, capabilities, security.
  • Usability human factors, help, documentation.
  • Reliability frequency of failure, recoverability, predictability.
  • Performance response times, throughput, accuracy, availability, resource usage.
  • Supportability adaptability, maintainability, internationalization, configurability.
The "+" in FURPS+ indicates ancillary and sub-factors, such as:

  • Implementation resource limitations, languages and tools, hardware, ...
  • Interface constraints imposed by interfacing with external systems.
  • Operations system management in its operational setting.
  • Packaging for example, a physical box.
  • Legal licensing and so forth.
Prototypes and proof-of-concepts

To clarify the vision, and validate technical ideas.

Proof-of-concepts are used to investigate technical feasibility of the system and programmers often do them instinctively. They are very simple one-purpose parts of code that test specific technology capabilities. They should be used very early in the project because they affect the feasibility of the system.

On the other side, prototypes are more complete. Their purpose is to test the system usefulness by presenting them to the stakeholders. They can be e.g. clickable "wireframes" - HTML code that acts like a final system should.

Iteration plan

Describes what to do in the first elaboration iteration. An agile iteration typically lasts for 2-6 weeks. It may consist of:
  1. An hour planning of the iteration.
  2. Rest of the first day is spent on designing.
  3. Rest of the time is spent on implementation, testing, integration and daily builds.
Following documents should be started in the Elaboration phase. That means I should also code in between.

Domain model

This is a visualization of the domain concepts. It is similar to a static information model of the domain entities. It is basically a conceptual model with classes from the domain along with their attributes, relationships and cardinalities. An example of the domain model (by Kishorekumar 62):
domain model example

Software Architecture Document


A learning aid that summarizes the key architectural issues and their resolution in the design. It is a summary of the outstanding design ideas and their motivation in the system.
The prime input of architecture document is the Supplementary Specification. We distinguish 2 types of architecture - logical and deployment. Logical is the more theoretical one, which describes the logical layers and deployment architecture is about physical distribution of the components.

The most common logical architecture method today is the layered architecture. This is described usually in the packages diagram. Sample layered logical architecture would be:
logical layered architecture example



Design model

This is the set of diagrams that describes the logical design. This includes software class diagrams, object interaction diagrams, package diagrams, and so forth. Main purpose of Larman's book is about this. Recommended reading.

However, if you don't have enough time, the most important things what I've taken from the book are:
  • Speaking of UML, Sequence diagrams are the key technique! They are more important than static diagrams and are often underestimated by novice designers.
  • Concurrently I should draw class diagrams. They are the most common from the static world of the UML. I can partially generate them from my sequence diagrams.
  • But good design is not about the UML. Understanding responsibilities is the key to good object-oriented design. (Martin Fowler)
  • GRASP design patterns are: Creator, Information Expert, Low Coupling, Controller, High Cohesion, Polymorphism, Indirection, Pure Fabrication and Protected Variations. They are general principles of good design.
Other documents

These document are not really needed for one man coding:
  • Glossary - key domain terminology, and data dictionary.
  • Risk List & Risk Management Plan - Describes the risks (business, technical, resource, schedule) and ideas for their mitigation or response.
  • Data model- important if designing also the SQL data tables.
  • Use-case Storyboards, UI Prototypes- A description of the user interface, paths of navigation, usability models, and so forth.
Finally after inception phase just start coding for god's sake :-)