Documentation – what should it be?

In the last few days I’ve been trying to understand and use EA’s Visual Execution Analyzer (VEA)  and at times have struggled.   To get an overview I checked out Sparx’s video and immediately on trying to replicate it failed, so consulted the user manual and white papers which, unfortunately, didn’t provide the answers I needed.  In many ways I found that the level of information was either too vague or too detailed (and not the right details).  I did solve some issues by searching on the Internet but as a last resort I’ve had to raise a support ticket with Sparx who I hope will provide the information I need.

I will add that its not that EA is significantly different  (worse) than other development products that I have used, it just happens to be the one I’m exploring at the moment.  On the plus side I got a relatively quick intial response from Sparx and worth remembering that I still have several long standing queries to other vendors who have not yet even acknowldge my requests!

This episode (which I must add isn’t an isolated issue) made me think about the topic of documenting software and the challenge it presents for all involved – the developers, the marketeers, the uses, the supporters.. . What documentation is needed, by whom and when.  And this adds the dimension of the documentation that is needed throughout the whole life cycle of the software.

Some 30 years ago, in previous lives,  when I asked for documentation there was usually plenty available, it arrived in a very structured form with different levels of documents with index documents to help ensure that you could identify the correct document to access the information required.  Needless to say the manuals could easily occupy a whole bookshelf!  And perhaps I’m looking through rose tinted glasses or just that I was younger, brighter etc it also seemed that more accessible and digestible.

If I step back from a specific product, I need to ask whether, in general, products have got that more complicated? There are certainly more features, but is it more that the approach to development and the associated tasks of documenting have changed.

In our new world as soon as we can’t find something we tend to google it and hope that somewhere out there the information we need is returned by our particular selection and sequence of words; the response may reference the vendors documentation but more often than not the answer (if found at all) is elsewhere.

  • What does this say about the state of documentation?  If the user can’t find the information they need will they remain a user?  Will they seek alternative products?
  • What confidence would you have that there is real knowledge about the product?
  • And more so, as the manager responsible would you be happy making an investment in the product?

This episode (which I must add isn’t an isolated issue) made me think about the topic of documenting software and the challenge it presents for all involved – the developers, the marketeers, the uses, the supporters.. . What documentation is needed, by whom and when.  And this adds the dimension of the documentation that is needed throughout the whole life cycle of the software.

To start with I can’t recall coming across many technical authors in recent times, they exist but I guess a lot of documentation is now done by the developers, who undertstand the product in detail before the start.  The argument for using a technical author is that they are usually not very familiar with the product so they check it out, ask questions and get the information they need to produce documentation for the different types of users.

One of the ideas I had in my mind in exploring the VEA and its code engineering in EA in general, is that as a development tool EA could improve on other IDEs. In particular, it could pull together the knowledge of a product in one place from its initial concepts through to the working code, test results and beyond capturing information throughout its life.

With information captured and maintained within EA (“objects” and the “relationships” between them) it would be possible to extract the information as and when needed to meet a specific purpose.  This does assume that all the relevant information is added into the model – in my experience this is the biggest  challenge. A whole range of documents could be produced in a variety of formats – whether as we see now – Word, Excel or HTML or in a form that we haven’t even seen yet such as an intelligent voice based interrogation and summary system that would engage in a discussion with the user and providing the information they need and possibly providing a personalised guided tour through the product as if an expert were sitting beside you. And dare I say that will probably be the best answer to the question I have raised but back to today.

Of course, EA is only a tool and although it provides the foundation it would need supporting systems and probably some other tools/extensions to fully streamline the associated tasks. But we can use this as the vision, and work with this in mind.

I also worry that in a world which is increasingly living with disposable products will we consider our software in the same light? If so what about the software that is built using other software, is there a danger that we are building on shaky foundations?  Will we become dependent on the quality of tools that can reverse engineer and extract knowledge from the products we use, to protect us from a lack of documentation.  But in the meantime how can we document to the level that secures our future?  Do we have to specify a best before date on our software so that those who exist in the wider ecosystem can manage their risk?

So for the documentation – what are the drivers – here are some example needs:

  • Information needed by those working and managing the development – this set of users will have varying needs from feature capture, analysis, and design coupled with the management of those tasks in a structure manner
  • Information needed by the user –  who is usually paying for the product, so that they can gain the real benefit of the product, and hopefully communicate positively to others in turn may become customers?
  • Information for those tasked with ongoing support – they may not be those initially involved with the developed, so how do we ensure that the relevant information is captured; needless to say there are a lot of design decisions which could get lost in the process and be significant in the future.  As an aside one of the statistics I remember well is the fact that 80% of the cost of software is its maintenance so if the information isn’t available then that cost could rise.

Can these be realised with using EA?  Probably!

Some good stuff I’ve found using EA is its ability to help with:

  • Capturing information and share the ideas
  • Managing the requirements
  • Supporting the analysis
  • Producing the initial code generation for the classes
  • Reverse engineering code into a model to get information that is not available in documentation!
  • Producing documentation in the different formats needed by the different stakeholders.

And with its open interface EA

  • Enables the transfer of data in and out, and hence provides some protection if for any reason you need to extract data in the future
  • Provides a framework for extensions that can be used to bridge the gap between the tool and specialist needs.

These were both key factors for me selecting the product over a decade ago.

Now before we get carried away by the product we should remember that the biggest challenge is not the tool but the people and the systems associated with its use, but that’s a topic for another day.

So not sure I’ve answered the original question but rather provided some random thoughts and highlighted some of the challenges that face any tool that will be of use to others developing, supporting, using and managing product development.

And so for me now, back to exploring EA and try to understand what exists, what works and how it works.  Have fun.