Why Technical Documentation Is Important In Product Development

Why Technical Documentation Is Important In Product Development

When I evaluate the software development market, I categorize it into three distinct types; formal, semi-formal and informal market. A lot of developers play in at least two, with some playing in all three. While a lot of people don't concede to the existence of these three distinct types, their interaction or mode of operation varies between each software development market. Where a formal communication style is encouraged in the formal market, you find that a less formal communication style is common in the semi-formal market and an informal communication style is a norm for the informal market.

store-4156934_1280.png THERE ARE THREE SOFTWARE DEVELOPMENT MARKETS WE SHOULD KNOW ABOUT

The formal market is one in which software development takes place in firms with a software engineering team or that takes place when an entity outsources the development of software solutions to a software engineering firm which makes it the most structured. The semi-formal market is when software development is contracted through freelancer platforms where the client puts out a request and several professionals submit their bids. It isn't as structured as the formal market but it still provides some form of structure. The informal is the typical market where there's little or no structure whatsoever, typical arrangements involve referrals or a direct relationship with the software engineer that takes the job. It usually starts with a "so you're a software engineer, can you build me a website and an app?".

potters-1985519_1280.jpg UNDERSTANDING THE PECULIARITIES OF THESE MARKETS

While the three different markets still find a way to get the job done some of the time, there are times when things go wrong and when they do you'll begin to appreciate the essence of a structured software engineering market for both parties. In a formal software engineering market, there is usually proper documentation involved in the design process, the client has most likely seen a mockup of what to expect and there are documents that specify what is to be built in detail to avoid ambiguity. In a semi-formal market, there isn't always a team involved in the project, documentation isn't always available, and when it is, it isn't as detailed as one will want it to be. A lot of times the team (if it exists) just "wing" it and hope for the best. In an informal market, 90% of the time there is no team, no documentation, one developer promises he/she can do it all and the design process is usually done on the fly. It can sometimes be the cheapest and the fastest of all three when everything goes well.

cube-3116778_1280.jpg RISK ASSESSMENT OF EACH MARKET

When things don't go well, conflict resolution is a lot harder with a semi-formal and informal market because there's hardly any documentation or structured team that can aid with negotiations or managing the expectations of the clients. A lot of clients don't understand that we put the "engineering" behind the "Software" role because what we do as software engineers is very similar to what engineers in other fields do, the assumption is that what we do is a lot like UI/UX and it isn't. The average assumption is that it's easy for software engineers to include new features in a product, it's about as easy as telling a civil engineer to make a building that is already on its second floor wider. because you can't see it with code doesn't make it any different. This one of the most important reasons why technical documentation is needed on projects, that way every stakeholder knows what is being built, what to expect and other necessary details. This can make it easier to resolve conflict and build better.