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 :-)

Comments

Post a Comment

Popular posts from this blog

Notes about the Clean Architecture book

The first look into the contents of the book was a bit scary. Some of these things were already explained in Robert Martin's previous books. Then I found out they are explained from a different (software architect's) perspective. Overall, I liked this book better than Clean Coder, but it was less useful for me than Clean Code book of the same author. Part I - Introduction The foreword contained two useful antipatterns: Too authoritative and rigid architecture. Speculative generality in software architecture. The main point of the preface is that not much changed for the last 50 years in software architecture. The rules of software architecture are the same regardless of any variable (time, type of project, ...). When you get the architecture of the software right, you magically don't need horde of programmers maintaining it. Chapter 1 - What is Design and Architecture? There is no difference between software design and architecture. There is a continuum of...
Read more

Notes about the Building Microservices

These are notes for my future self about Sam Newman's book, Building Microservices 2nd edition.  Preface Microservices are an approach to distributed applications that use finely-grained services and change, deploy and release them independently. Microservices have become the default go-to architecture when designing system, which Newman finds hard to justify #surprised and want to share his view on why. Foundation Chapter 1 - What are Microservices? Microservices are independently releasable services modeled around a business domain . They are kind of SOA, but the one which is opinionated about how service boundaries should be drawn and where independent deployability is the key. Microservices should implement information hiding and expose their API in some way, e.g. via REST/JSON API or by emitting events. They should have their own database schema. To highlight that the services are as independent as possible, Newman draws them as hexagons, a homage to Alistair Cockburn's H...
Read more

Notes about A Philosophy of Software Design

My notes about the book by John Ousterhout. It is quite a short book. Originally I made a mistake of reading just the Conclusions of the chapters but there is a lot of contents not in the Conclusions. After really reading the whole book, I started to like the Red Flags and other small pieces of hints. Chapter 2 - The Nature of Complexity Complexity is anything related to the structure of a system that makes it hard to understand or modify. Isolating complexity in a place where it will almost never be seen or touched is almost as good as removing it. There are many symptoms of complexity: Change amplification - when change requires modification in many places.  Cognitive load - how much a developer must know in order to make a change. Sometimes more code is simpler than less code because of cognitive load. Unknown unknowns - it is not obvious which places should be modified or what knowledge the developer must have to make a change. Complexity is caused by 2 things - dependencies a...
Read more