Role of documentation and software architecture in Cubix

Cubix – An Agile company

Cubix believes in delivering quality products and on-time software development to their Customers. This is what satisfies us the most as a software development team and is the reason for our customers’ happiness as well on every successful project that we deliver and trust us with granting in more projects. We recognize the importance of software in almost every industry be it Medical, Areo-Space, Finance, Automobiles, Hospitality etc. and we consider the main ingredient of successful software development with the current evolution is by following Agile Methodology. Similarly, the development teams’ commitment for continuous improvement is what makes an organization successful.

Cubix not only follows Rapid Agile App Development process in every project to best fit in the system but also practices as an agile business itself as well where we have the ability to quickly adapt to market changes. Being an Agile company gives us following reasons to succeed:

First-Mover Advantage – Probably the biggest advantage of taking an agile approach is that you can have first-mover advantage over your competitors. While they’re busy planning and perfecting, you’re out there making sales.

Motivates The Team – Working at that speed, and iterating quickly is incredibly exciting and motivating for all of your employees. The Progress Principle is important for motivation, and working on the same project for months with nothing tangible to show for it can be quite demotivating.

Involves Your Customers – Your customers get a constant sense that your company is growing because you keep releasing new features. It also allows you to adjust to customers’ demands, keeping them happy and with you longer.

Within different circumstances, we are always looking for evolution in the latest methodologies of software development and software engineering techniques. For us ‘Agile’ is not just a process, it is a Mindset that we follow.

Documentation in Agile development

A good software project begins with excellent communication among all team members with simple, clean and efficient documentation which is important to project success. Many companies considers ‘Documentation’ as a low priority element or a backlog item even tough working within the agile framework of software development. In Cubix, it is different because we emphasize on the quality and believe that a good software project must have an up-to date and meaningful documentation. Using agile methods, many prefer working software and minus the comprehensive documentation. The explanations for this phrase appearing in the Agile Manifesto are several, but for us, the most salient is that if we have an extensive documentation, it often creates an illusion that we do not need to talk or have discussion with the client to understand him better, and rather the provided document will apparently cover this function.

However, this thinking is based on precarious fact: it is assumed that whoever writes the documentation really understands the business, and the responsible person (or committee) was able to clearly demonstrate all the features in the system. Also it is believed that these ‘Writers’ will interpret the text well, do not forget potentially important details and that this document will always be updated as the changes happen.

The principles behind agile practices have not yet been fully understood by many of those involved in software development, and even today it is quite common for agile practices to be adopted without criteria, creating an alternative and inefficient software process. In addition, there are much misunderstanding and myths about software architecture, documentations and their correlation to agility.

To address this problem, Cubix Development Team has developed its own way of working with agile software development methods, where documentation are not considered as a backlog. We involve the entire project team in the systems architecture documentation processes displaying the importance of a simple but robust documentation model and breaking paradigms. This allows the developers to be a part of decision making process along with software architecture design and documentation model process which also helps us in future projects as well.

The Agile manifesto and documentation

The adoption of agile software development practices initiated after the Agile Manifesto published in 2001, after which increased the number of “agile projects” rapidly. Today, in most companies there are numerous self-proclaimed agile projects. It is as if any project with little documentation and some related practices were raised to the official level of “agile design” and thus ended quickly, cheaply and well.

However, those who have some experience knows how to complete these projects, usually in the worst possible way. The main problem in these cases of failure is the lack of knowledge about how agile manifesto principles shape the most common agile development practices and this brings with it the illusion that the simple adoption or removal of certain practices elevates a project to agile status.

In this situation, one of the main practices eligible for removal by those who do not understand the essence of agility is to decrease or in more extreme cases is to end the documentation. Since a lot of people associate documentation with bureaucracy and lack of agility.

In practice, the Agile Manifesto phrase means that we avoid wasting time on documentation that will not be read or that will become obsolete swiftly. Instead, we prefer the software itself to be its documentation, by:

Automated unit tests: Code that checks a method / function / class for a given controlled scenario with its expected result. This is documentation for the developers that who will work on the codes in the future.

Automated acceptance tests: Code that simulates what the system user will do and its behavior using a feature. This is documentation is for the fact when the team changes what a particular code does.

Clean code: Actively practicing to make the code clear and consistent so that the next developer that works on it does not have to spend time uncovering or understanding what it does. This is a massive umbrella of good practice in day-to-day development.

If the code is still not good enough for anyone to understand its dynamically generated documentation, an automatic generation document tool (language-specific tools) is used to gather the relationship between the parts and classes of the system. Often, UML is used and also there are several tools that analyze a code and generate diagrams that reflect the current state of system design and architecture. Of course, depending on your environment you may be required to provide certain documentation to the customer. In that case, we do our best to avoid unnecessary work but unfortunately we have to perform within the business etiquettes.

How to organize software documentation at the end of each iteration and how to reconcile agility and software architecture?

The most common method of making sure to deliver mandatory documentation is to add a step to our ‘Ready Criterion’ so that the entire team knows clearly that every item developed must be documented and also that any bottlenecks in this step be explicit to all.

Many in agile teams think that software architecture is a bureaucratic and agility does not provide room for documentation. In agile projects, documentation is actually reduced but if the architecture is left out? Quite the opposite.

In an agile process, software architecture is a paramount to any project. However, the idea that software architecture and its documentation has no place in agile methods has been widespread even though it is possible to reconcile both taking into account the architectural purpose promoted by the system disciplines and the concerns in terms of software processes associated with agile methods.

It is important to understand that application document especially the software architecture document is an object of extreme importance to software development for multiple reasons. Among them are the formal definition of the system architecture and to demonstrate basic understanding to all team members. Generally the software architecture document describes the architecture of the system as a whole which refers to the constraints, organization, standards, and responsibilities of modules and components.

Software architecture and documentation are matters that go in hand or should be related as the main reason for the success of a system is because of its architecture. Attributes such as cohesion, coupling and modularity for example are treated at the architectural level and these architectural decisions should be documented to propagate knowledge among those involved and concerned about the system. Thus, a project executing agile to achieve the high technical quality cannot give up the documentation.

Although it is a common thought of having a little or no documentation in agile projects. This type of thinking is inaccurate and to have solution to this situation, the next para will explain how to reconcile software architecture and to keep the project well documented without giving up of agility.

What does Agility manifesto means in software development?

Agility in software development represents a set of ideas and practices that have long arisen under the influence of some relevant members of the development community. These ideas began to evolve from the agile manifesto, a series of principles launched in the year 2001 with the aim of simplifying and changing the way software projects were viewed.

The main points raised by the agile manifesto were:

Individuals and interaction between them rather than processes and tools.

Software in operation rather than comprehensive documentation.

Collaboration with the client rather than negotiating contracts.

Respond to changes rather than following a plan.

Within the Agile manifesto points there are a number of principles that provide guidelines to the agile methods as a whole. However, the manifesto itself agrees that there is no absolute certainty in these principles because it says that “we are discovering better ways to develop software by doing it ourselves and helping others to do it”, that is good practices for software development can arise at any time and likewise can be replaced or supplemented by even better ones. Agile principles aims to provide a series of values on which effective software development practices are based.

The considerations raised by the agile manifesto describes what is most valuable in software development over other ideas. It also considers audacity in formal processes. It is very important to note that this does not mean that ample documentation is worthless. It makes sense that working software has more value than comprehensive documentation, after all what’s the point of having comprehensive documentation and a software that does not work? However, many people interpret these assumptions of the agile manifesto in the wrong way thinking that one should have functional software and no documentation.

Agile methods do not eliminate all documentation and the main document in a software project is the software architecture document which should definitely not be removed from any of the project artifacts.

Regardless of the process used in software design, architecture will always be present either accidentally (when it exists simply for implementation decisions) or intentional (when there is concern about its design and maintenance).

Synthesizing the reconciliation of software architecture and agility, we can conclude to an understanding that architecture cannot be seen as a software process to the point of having artifacts and documents created without utility. It must respect the process. Thus, in agile methods architecture must be evolutionary as the process dictates. The architecture should reflect the current design and must accommodate the changes as agile methods implies to accept changes at any time and the most important part is to understand that all software has an architecture whether intentional or not but ideally it is intentional.

Outcome

Good agile coaches explains “doing agile” vs “being agile.” In agile, there are tools like daily stand-up meetings, retrospectives at the end of a sprint, etc. but keep in mind these are just tools. The real change comes within the company culture. Is the company still a command-and-control type of environment? Agile is about quickly adapting to change, and not being afraid to fail. As a leader, you need to create the type of environment where failure is not only accepted, but actively encouraged.

Agile is more about how your team approaches problems, not the tools used to solve them. Experience challenging your team to limit the number of design objects and embrace discussion over documentation. You’ll save time. You’ll save your budget. And best of all, your team can start building products faster, stronger, with more ease.

At Cubix our team’s goal is always to make the best product possible with every participant engaged and working together to solve the same problems.

Learn more about our Agile Methodology.