a design document

In the last month i’ve been trialing my participation to a new project. The project is greenfield in some sense as it involves the extension and possible rewrite of an existing system.

My first moves within the team were some steps back, because every good software design needs to be rooted into good specs and a clear idea about the value to be added.

Initially it was not clear to me how to collaborate on documents. I started interacting on the existing Google documents but that didn’t feel effective. Eventually i settled on working on a different document, which would mention the existing ones and be a link between them and the software to be developed.

I started the document on Google but soon copied it to a markdown file in a repo dedicated to the new project. This presents some limitations but also some advantages like: - organised changes and discussion - higher portability - stick with the code

The last point is very important to me. We wanted the document to contain something that i found missing in many projects i worked on: the software design.

Most software i worked on was not designed, but just grew out of a few starting intuitions, often about using such and such technology and connecting such and such system. Sometimes a prototype has been considered as an exhaustive description of the software design. Often the maintainers had no track of the reason why some decisions were made. When problems arose, solutions were found that potentially violated the original design, but rarely the original design when it existed, was updated.

I consider proprietary formats or non-inclusive formalisms or skills to be one of the main reasons why design documents are not updated. This is why i wrote a design document in plain English and in a plain text format.

While i did design work in the past, it was mainly through sketches and prototyping. Before this document i never had the opportunity to draft the description of a system in natural language, and i must say that i was rather impressed by the expressive power, flexibility and portability of this approach. I need to add that most of the power is, in my opinion, due to a style of writing, whose main features were:

• be as much as possible essential, succinct, plain and understandable
• collect facts and shared opinions, rather than personal opinions
• mention the sources for opinions and facts
• be reasonably structured and modular about the topics covered, in order to facilitate maintenance and modification

Needless to say, this took time, but it was some of the most productive time i had in a while. Whole backend components were moved in and out of the system by means of simple sentences in our natural language.

The software design document places itself between the user specifications and the roadmap made of milestones, in a design process that is lean but keeps some important distinctions. The document does not state how we will get to the system, but just which kind of system we want to build.