Technical Authoring

Current state of software development

No one can deny that the evolution of software processes towards the Agile/agile philosophy hasn't transformed the way in which we develop software.  Agile brings all kinds of benefits like closer interaction with the customer, faster time to market, quicker turnaround times from requirements to solution etc.  But there is an underlying denial of what is being delivered in some aspects.  This denial is in the level of documentation.  Nothing in the Agile manifesto says don't document your architecture, analysis or designs.  It's about getting the right level of documentation.  But we encounter in many organisations a complete lack of documentation.  Consider the following questions regarding your organisations approach to its SDLC (Softwware Development Life Cycle)

• Do you subscribe the philosophy of self documenting code?  Can you really look at the code determine the problem that was being solved?  Can you really look at the code and quickly understand the design that has been employed?  
• If everyone who worked on the software were to leave how easy could it be changed, upgraded and how quickly?
• Can impact analysis be easily performed?  If the requirements change how easy is it to determine where the impact is in the software?  If the software were to be modified from the ground up how easy is it to determine which original requirements are impacted?

If you can honestly answer yes to all of the above questions then you're in a great place.  Leave this page and carry on doing what you have been doing.  But if you answer no to any of the above or have some doubt about any of the above then continue reading.

TDD, ATDD and BDD

All of these approaches lead to fantastic ways to develop and maintain software components and in actual fact it's quite easy to determine some aspects of the problem being solved by looking at the tests.  More so with ATDD and BDD and not necessarily with TDD on its own.  The problem is, when you have a system that is comprised of many components, none of these techniques actually describe the complexity and thinking behind the design of the components and their inter-relationships.  You would need to statically and dynamically walk through the code.  Depending on your level of experience in the language this could be done quickly.  However, there is nothing stopping you from making some very bad assumptions regarding what the software is actually doing.  

How can we help

Our authoring service is designed to build models that meet your level of documentation.  We subscribe to principle of "the right of documentation for the problem at hand".  The purpose of the documentation is to aid

• an understanding of what the software actually looks like (so we can build models that are developer focused)
• conversations amongst the developers and customers (so we build models that can be read by both developers and customers)
• conversations amongst architects and developers
• forward and backward impact analysis
• the maintenance of your software

How do we work

Once we gain access to your software, we will develop some ATDD tests to help define the requirements (we only do this if no ATDD tests already exists).  We will then work through your software and develop a number of UML models such as class, sequence, activity, state, deployment, and component diagrams etc. of your software with accompanying textual narrations.  We then finally use a number of techniques to determine the best way to present the models in a manner that suits the way you work.

How to get started

Contact us today and see how we can help you.