The other day I was writing some code for an EA AddIn in which I was adding elements to the model. The customer was keen to be able to use the auto numbering feature provided by EA, so my immediate thought was to check the documentation and make the relevant changes. So I look at the documentation but there is no mention about the auto numbering feature for thr AddNew method. As the EA AddNew method is used extensively across EA I suspect that its relationship to the Auto Numbering feature was missed (or perhaps in searching I’ve missed it). After a few guesses and tests I managed to find one answer – it appears that if you set the proposed name of the new element to “” AND if auto numbering is enabled for the desired element type EA will do it’s thing and a name provided as per the rules.
Now it’s no surprise to me that with such a complex product and vast amounts of information to include some of the details are missing. Then keeping documentation up to date with code requires good systems and careful management.
We live in a world where there are plenty of information sources and for some some products I find out more from Google than reading the formal documentation!
So thinking about using this undocumented feature – the risk I see is that in the future the developers may decide that they want to change the way it works, at which point my code would stop working. And dare I say I have no grounds for complaint as nobody had promised the interface existed in the 1st place!
If I look at a broader range of examples it does raise the question of how best to provide documentation and present it to the various audiences.
Starting at one end of the spectrum – the code.
I’ve heard it said that if you provide the code all is revealed, I’ve even heard developers, who are poor at documentation, citing this as the reason for not providing more formal information for their work. However, I’d suggest that this isn’t necessarily a solution. In my career I’ve done several projects where I have been asked to document existing code. I can tell you that with 1000’s lines of assembler and a requirement to document all the rules/formulas its not a task for the faint hearted. Although that is an extreme case but in other examples I’ve seen that the code, although it may work, didn’t fully reflect the coders aims!
So why not reverse engineer the code into EA. In my explorations of EA I have “played” with reverse engineering some test projects and apart from consolidating and being able to annotate (useful) it doesn’t remove the hours of pouring over the code. However, it does provide a place to capture information and produce documents that can have some structure.
So if we come up a level and assume that our developers have produced documentation in or outside of EA – are we happy that it accurately reflects the systems they have produced? How we get closure on the completeness, accuracy and validity of the documentation?
Now if the developers had started with EA and maintained some degree of synchronisation of information – so at least all the functionality and key design (and user) information is captured then there is a the possibility of a useful knowledge base from which to generate the required documents.
So what about providing the EA model as the documentation – clearly there would need to be some contextual stuff to communicate the way the model has been produced or would this be similar to providing the code. I know that working with different teams the EA models they produce can vary enormously and hence only of true meaningful to the developers. So not sure that is the answer.
One approach I have taken is to develop models purely as information sources. For example I have a model to help me with my EA work that contains both the EA object/EA AddIn models and other related stuff e.g. the undocumented features. Furthermore I can use part of it as the seed for all new AddIn’s – copying the AddIn model, modifying the required class/methods, document etc and when ready to start coding press the generate code button.
Outside of the coding stuff there are many other systems that we all interact with on a daily basis and for which we usually have very little, if any training, and we make assumptions based on our experience. Clearly those born into our computer based world are used to a trial and error discovery mode of learning (I’m far too old). But is self discovery, potentially augmented by Google and other search resources, the way or is the a better way. However, I think it also changes expectations – if you tend to find your information by trial and error there may be less emphasis on producing the formal documentation that accurately reflects the stuff you produce.
So back to the main point – how best to document – and ensure that all the relevant information is available. A big subject and I know I don’t have the answers. I just know that over the years it has changed but I’m not sure it could be said that it has improved. Of course, things have become more complexity and our expectations have changed.
I have tried using different approaches and embracing new ideas; here are the key tools I use for information capture – and as the sources for documenting stuff.
- Wiki – to try and ensure I capture the snippets, so I dump my findings into a Wiki as I go – a useful repository, searchable, and provides a mechanism into which to add a little bit of structure
- Mind maps – to capture new stuff/ideas before any structure is clear in my mind. And can be a great tool for putting some structure in place and producing documents.
- Spreadsheets – to capture my lists and to help with planning; and can be input or output from EA.
- EA – to model stuff in a more formal manner – usually when I’ve got through the brainstorming and have an idea of what I’m aiming to do. By the time I have a real project I like the idea of stuff being in a single place. Now of course I have to sync data between different sources and with different people – but that’s for another time.
Just a few more thoughts on EA.
- If we consider EA as a tool that manages things and relationships it can be used as a great place to store stuff, not least as it provides a means of linking the “formal” modelling stuff with other information of interest.
- With stuff in EA it is possible to export and produce documents both directly or indirectly – and in a range of different formats that ideally meet the needs of the target audience.
- If we provided models as part of the documentation how meaningful would a search for information by a 3rd party be?
- I have a concern that without some structure and rules applied that a model could become messy, unstructured, encounter duplication and develop relationships that are meaningless. Just a reminder of the garbage in garbage – can’t escape it!
So in conclusion, in writing this it just reminds me that there isn’t an all-in-one solution to the documentation and probably never will be, but there will always be undocumented features!