Upgrade your documentation by using software development diagrams

Everybody who ever participated in a software program mission is aware of how vital it’s to have good documentation. Not solely can it make the event course of extra environment friendly, however it might take the product itself to the following stage. At The Software program Home, we’ve got developed our personal means of perfecting the mission documentation. How does it work? Let’s simply that it actually drives dwelling the purpose {that a} image is value a thousand phrases.

what they are saying…

However have you ever ever puzzled what actually makes nice documentation? Is it how a lot info it has? Or maybe it’s all about utilizing exact standardized terminology?

So as to discover the reply, let’s go on a journey by way of various initiatives we’ve had the pleasure of engaged on right here at The Software program Home.

The problem of writing good documentation

Once we take over a brand new mission from our shopper, we sometimes get a listing of necessities within the type of a written doc, a listing, or ready-made consumer tales. Regardless of the shape, the necessities sometimes fall into two classes:

• means too brief and filled with psychological shortcuts taken out of context,
• extraordinarily detailed, and complete.

Which model is healthier. At first look, it appears fairly apparent that it’s the latter. However is it actually?

Think about a situation by which you’re the Product Proprietor. You may have simply devoted quite a lot of hours with a view to create very complete documentation. Every little thing is there, right down to the smallest particulars, together with all the sting circumstances and processes. It looks as if all there may be to do is for builders to take a seat down and write the app of all of the stakeholders’ goals. After which, one after the other, these very stakeholders come to you and ask how this or that characteristic is meant to work, what it’s all about, and so forth. 

What went incorrect? In any case, you gave all of them they wanted. They’ve stunning complete documentation. Why do they preserve asking so many questions? What are you able to do to stop it? 

Belief us – we’ve been there. We’ve been striving to seek out solutions to those questions for fairly some time. It got here to us steadily. What’s it? It has to do with… drawings.

Fundamentals of software program improvement diagrams

Once we take over a brand new mission, we all the time begin by asking concerning the documentation. Even after we get conversant in it, we like going by way of the app to know the processes that happen inside it even higher. That’s how we approached yet one more mission we received to be part of – for a shopper from the gaming business,

Documentation that doesn’t scale – a case research

From the consumer’s perspective, the app appeared to be intuitive and straightforward to make use of. The mechanics have been easy: you play, you get factors, after which alternate them for varied perks.

Nevertheless, the extra we familiarized ourselves with how the reward system labored within the documentation, the extra we realized that the precise mechanism behind it’s actually advanced. The Confluence web page that contained the app’s enterprise logic was a 20-minute learn. What’s extra, it included tons of hyperlinks to different paperwork.

Fortunately for us, there have been some individuals on board who knew the mission just like the again of their arms. They have been there to reply our questions. However that begs one other query – what if these individuals left the mission? Who would have the ability to shortly debug, modify and enhance the present enterprise logic and preserve the system from falling aside?

The prospect itself is kind of scary. Fortunately, it doesn’t must be that means.

Our crew obtained new necessities. It referred to as for updating a serious performance in a means that may make it much more advanced than the present model. It might rely on various logical circumstances. Quickly after the primary iteration, we determined to visualise the logic within the type of a diagram.

At the moment, we didn’t use any formally standardized languages resembling Enterprise Course of Mannequin and Notation (BPMN) or the Unified Modeling Language (UML) – extra on these later. On that event, we simply drew a easy diagram, which included various paths the consumer might comply with after they met varied circumstances. It used a easy yes-or-no logic:

Each our crew at The Software program Home and the shopper shortly realized simply how useful this method is. The diagram supplied quite a few advantages:

• It helped us establish some extra dependencies related to our implementation. 
• We have been additionally capable of finding gaps within the necessities. Opposite to what we have been instructed, there have been lacking edge circumstances, which we have been in a position to flesh out.
• The brand new intuitive type of documentation made it a lot simpler for QA specialists to do their job by giving them a high-level top-down view of the system.
• The exact same side turned out to be helpful for builders as effectively.

The optimistic suggestions from the shopper was crucial for us, we succeeded in completely altering the best way documentation is made within the mission. The shopper noticed how helpful it was in the long term and tailored the method for good.

As you may see, visualizations actually do make a distinction. However there may be extra to that than scalability.

We’ll now present you one other case research, by which diagrams helped us come up with an enormous mission that featured advanced logic, compounded by the presence of quite a few third-party items of software program.

Misunderstanding, psychological shortcuts? Visualizations to the rescue – a case research

It doesn’t take a logistics professional to know the way the package deal supply course of works. It begins with shifting the package deal from one warehouse to a different after which to the shopper. Nevertheless, once we joined a mission for a logistics firm, it turned out that the entire logic of managing deliveries, items, and warehouses is means tougher than it appears.

To make issues much more sophisticated, the mission used Google’s Blockly – a visible code editor add-on for net and cellular purposes. The software added guidelines that changed out there reserving slots for deliveries. As soon as once more, with a view to absolutely perceive the way it works, we used diagrams.

Written necessities are fairly error-prone attributable to their sheer measurement. It’s also doable that imprecise terminology or psychological shortcuts can create misunderstandings for the readers. Diagrams handle these shortcomings. They make it doable to current the logic within the type of a tree of dependencies that’s straightforward and goal sufficient to place everybody on the identical web page quickly.

After experiencing so many advantages of diagrams first-hand, we moved to speculate much more effort into utilizing them. We wished to make diagrams a staple of our improvement course of.

This referred to as for a extra systematic method to this subject. Enter…

Modeling languages at The Software program Home

Diagrams aren’t something new in software program improvement. UML diagrams debuted again in 1996, whereas BPMN received its starting in 2004. Regardless of that, up till not too long ago, we haven’t received to make use of them a lot in observe.

There’s an ongoing debate inside the enterprise analyst neighborhood concerning the necessity to meticulously adhere to official standardized languages. It’s a really advanced topic. Along with totally different modeling languages, there are additionally many kinds of diagrams in advanced software program techniques, together with: communication diagrams, package deal diagrams, behavioral diagrams, interplay diagrams, structural diagrams, state machine diagrams, sequence diagrams, element diagrams, class diagrams, timing diagrams, exercise diagrams, or the deployment diagram, interplay overview diagram, composite construction diagram, class diagram, and object diagram. And that’s hardly an entire listing!

Nevertheless, at The Software program Home, we discovered a solution to incorporate standardized modeling languages seamlessly into our course of. We sometimes use them at particular phases of the mission, once we study intimately concerning the necessities for creating a brand new app or performance from the shopper.

Naturally, we haven’t given up on less complicated ad-hoc diagrams. We use them throughout mission workshops with a view to shortly visualize concepts for the shopper. Subsequent, we transfer our visualizations into standardized languages. We discover BPMN particularly useful as a result of crystal clear means of representing occasions it gives.

Because of BPMN, we will design easy processes resembling this one:

We are able to additionally go for one thing extra advanced:

Only recently, we had an opportunity to work with BPMN on a mission from the academic sector. 

Utilizing standardized modeling languages at TSH – a case research

Our activity was to revamp and optimize the administration system of our shopper. Each workers and shoppers used the panel to handle their time and schedule conferences. There have been a number of processes and kinds of customers concerned. We needed to discover the enterprise processes that present probably the most worth and produce extra focus to them.

Once we begin a brand new mission, there may be all the time a storm of concepts coming from lots of people on the identical time. We weighed them in opposition to the necessities gathered from the shopper and visualized them utilizing BPMN.

Over the course of the mission, we observed that varied kinds of crew members profit from the visualizations:

• Programmers can simply map their code to the system as a complete. One look on the diagram places their work within the context. 
• Designers perceive how varied elements of the techniques work with one another. Because of that, they create designs that match enterprise necessities with fewer iterations. 
• Diagrams have been additionally helpful for all new crew members, no matter their function. It eased and sped up the method of actually entering into the mission.
• You can separate consumer tales from enterprise processes. It makes it simpler to establish and shut all consumer paths.
• The diagrams have been additionally discovered to be helpful to plan the work for future sprints.

As soon as the high-level work was achieved, we have been ready to make use of diagrams to go even deeper into the system.

A top-down method

Diagrams continued to be very helpful at a stage once we determined to divide the system into smaller processes and describe all of their enterprise and technical points.

The UML diagram (all kinds of UML diagrams) is one choice to decide on for that sort of work, however at The Software program Home, we particularly benefit from the C4 mannequin. As a matter of reality, C4 is a leaner graphical notation method largely based mostly on UML. After creating UML diagrams for a very long time, we realized that some components could possibly be achieved quicker utilizing C4. We used it to visualise the system’s structure in addition to the containers and parts that comprise it.

Modeling language – execs and cons

We decided among the commonest execs and cons of utilizing standardized information visualization and modeling languages resembling BPMN or UML. They’re based mostly on suggestions we obtained from all kinds of customers, together with PMs, QA specialists, software program builders, and designers.

The professionals

These are among the commonest execs talked about by all mission members.

1. Standardized naming

Each business has its personal jargon. The Product Proprietor tries their greatest to get all crew members conversant in no less than the fundamentals of it, however it’s nearly by no means sufficient. Visualizing the system and concepts goes a protracted solution to amend that. It abstracts away the jargon. Along with that, whenever you don’t perceive one thing, you may all the time simply level along with your finger (or mouse cursor).

2. Advantages of the DRY precept

DRY stands for don’t repeat your self. To many builders, it is without doubt one of the most vital rules of fine programming. When adhered to correctly, it makes the system extra environment friendly and scalable.

Diagrams allow you to stick with DRY as a result of they make it a lot simpler to place collectively in your head how this entire system is meant to work, what belongs the place and so on. In fact, doing so with written textual content isn’t inconceivable, however it seems that many builders that work with such documentation resort to making an attempt to attract it anyway.

3. Making sense of advanced logic

Breaking down an enormous downside right into a bunch of smaller ones is beneficial, but it surely takes a while. Typically, even the small ones take hours of time you spend consulting with varied specialists, gathering necessities, closing data gaps, and so forth. We realized that lots of these hardships are avoidable so long as there are diagrams to indicate everybody the best way. It interprets into hours of time saved.

4. Streamlined documentation improvement

Diagram-as-a-documentation can also be fairly a handy mannequin. You want documentation anyway – why not make it within the type of visualizations? And when necessities change, all it is advisable to do is replace the diagram. In our expertise, it takes a lot much less time than going by way of cumbersome written documentation with a view to edit all mentions of a given phrase.

The cons

There are some complaints about diagrams in software program improvement.

1. Frequent diagram revalidation

There are initiatives by which necessities change very regularly. Each time it occurs, it is advisable to replace and revalidate your diagrams along with your crew. It’s value doing, but it surely does take time.

2. Barrier-to-entry for standardized languages

Whereas well-designed easy diagrams are extremely intuitive and take not more than a few minutes to know, the identical just isn’t all the time true for people who adhere to standardized notations resembling BPMN or UML. They introduce jargon on their very own. New crew members have to study it. Fortunately, this data is very transferable.

All in all, it looks as if the professionals of diagrams vastly outweigh the cons. 

In case you and your crew are keen to place within the effort and time to study standardized graphical illustration and modeling languages, you’re not going to remorse it.

Software program improvement diagrams to the rescue?

Over the previous couple of years, we’ve got made information visualization an important a part of our methodology of mission setup and takeover. 

We use it to create your entire documentation in addition to enterprise logic. We depend on it for cooperation with shoppers and with one another. It grew to become an integral a part of the entire improvement course of. We went from easy ad-hoc diagrams to implementing standardized graphical illustration languages and strategies. Within the course of, we discovered that:

• Even detailed documentation may not be very useful to somebody that didn’t take part in its creation.
• The larger and older the mission, the extra of an issue non-intuitive documentation is.
• By introducing easy graphs, it can save you time, discover bugs, and achieve new insights into the system.
• By introducing standardized languages, you may successfully enhance all of the points that make up the method of growing and sustaining a software program mission.

As for the reply to the query at first of the article: nice documentation is one which instantly gives a beginner with all of the context and high-level info they should perceive how the system works and what they will do to make it even higher.