Documentation queries for the software

[hamishmb]

Hi all,

As I start to wind up river system work again, one of the things I want to do while I refactor some of the code is improve the documentation. I woud like to do this to improve our common understanding, but also make life easier for those who will come after us.

At the moment, we have some API documentation, which while incomplete, has fairly good coverage and detail. I plan to improve this in the near future.

I also understand that we have flowcharts for some of the main methods. IIRC, these are now rather out of date, and I think some of them may be missing or incomplete too.

I was wondering whether any of the following documents might be useful for me to create:

• A glossary of terms used in the software (do we already have one?).
• Some basic class diagrams to give a better overview of how the classes interact.
• Some basic object diagrams to show how the software runs in particular configurations (eg on the NAS box, sump pi, and lady hanham pi).
• Flow diagrams for some of the other threads (for example the sockets thread, and the monitor threads).

Do those sound useful, or would that stray into documenting for the sake of it rather than with a purpose?

[PatrickW]

I have long had it at the back of my mind to create some documentation of a high-level, diagrammatic/conceptual nature, describing how things are supposed to work together in the software. We have a lot of documentation of details (e.g. how the code works in close-up detail, what the various different methods and functions do) but not a great deal to explain the bigger picture.

For example, I have thought about creating some diagrams that explain, briefly and simply and on a conceptual level, how the state machine classes I wrote are supposed to be used to build arbitrary state machines, because that is something I would personally find useful if I was coming in as an outsider. It's all very well having the classes documented in the way that they already are, but if you have missed the basic concept that they implement, then reading the class documentation might not get you very far.

I also thought about doing a block diagram or two that just outline the main components of the software system, their responsibilities and how they fit together; at a higher level than classes. i.e. framework vs. logic, database, web GUI, and the manner in which they are interfaced with one another. Currently this is not at all obvious when you are coming in fresh as an outsider, and it takes quite a bit of reading the source code and documentation to figure it out. (At least, that was my experience.) So, such a diagram would be an aid to quickly grasping the big picture and then zoning in on the relevant component. It would be akin to a class diagram, so it wouldn't show every instance individually or get bogged down in details.

Alas, I have been very short of free time lately, so it would be unwise of me to make promises of diagrams at this precise point in time.

I think a glossary of terms could potentially be useful, and would fill some of the same gaps as my proposed block diagram, but the risk does exist of defining terms for the sake of it. Perhaps you can devise some kind of criteria to decide whether a term is important enough and sufficiently non-obvious to put in the glossary.

Class diagrams tend to be at least marginally useful if you already have them, but in my opinion the effort required to create them and keep them up-to-date is not necessarily commensurate with the benefit of having them to hand. I think it is worth being selective about which classes to show and in what level of detail. We already have documentation for the methods and properties of classes, so I would suggest diagramming primarily just the relationships between the classes, to avoid duplicated work.

I'm not sure what the object diagrams and flow diagrams would be used for, but they might be useful. I think I'd need an example to understand what you intend. Perhaps it is worth considering what human questions the diagrams are supposed to be answering as a guide to how important they may or may not be. Again, maybe it is possible to make them more useful by making them less detailed and higher-level. For example, a flow diagram that shows a pseudocode principle of operation rather than all of the implementation details. Or perhaps two diagrams, to show both the pseudocode (pseudoflow?) and the implementation.

Sorry, this was a bit of a wall of text, which is slightly ironic considering that much of it is written in favour of summarisation.

[TerryJC]

I'll say up front that my responses here are influenced by my background in writing documentation for Industry and particularly for MoD. The approach for this activity tends to be prescriptive and (perhaps) not appropriate for documenting modern software.

When I wrote the original Requirement and Design Specifications for the WMT River System, I therefore followed the 'rules' that I had learned at work. Two points:

• These documents were largely written before any hardware or software had been implemented and simply outlined the aims and approaches to be taken. Detailed design was included, but of course changed as lessons were learned.
• These documents were (mostly) updated once the system was installed and working, but I made no attempt to do much with the code because I didn't feel that my skill set would allow me to do justice with it.

Alas, I have been very short of free time lately, so it would be unwise of me to make promises of diagrams at this precise point in time.

Understood.

I think a glossary of terms could potentially be useful, and would fill some of the same gaps as my proposed block diagram, but the risk does exist of defining terms for the sake of it. Perhaps you can devise some kind of criteria to decide whether a term is important enough and sufficiently non-obvious to put in the glossary.

The problem with only putting the non-obvious terms into a document is that there is no way of knowing what is obvious to new developers going forward (as you've hinted at). The MoD mandated that all terms be included so that this problem never arose. I too thought that this was over the top until one of our Marketeers told me that 'AC' stood for Air Conditioning. You are never completely sure who the audience for a document will be.

Class diagrams tend to be at least marginally useful if you already have them, but in my opinion the effort required to create them and keep them up-to-date is not necessarily commensurate with the benefit of having them to hand. I think it is worth being selective about which classes to show and in what level of detail. We already have documentation for the methods and properties of classes, so I would suggest diagramming primarily just the relationships between the classes, to avoid duplicated work.

I really have little knowledge in this area, so I'm afraid that I have to leave this discussion to Hamish and yourself.

I'm not sure what the object diagrams and flow diagrams would be used for, but they might be useful. I think I'd need an example to understand what you intend. Perhaps it is worth considering what human questions the diagrams are supposed to be answering as a guide to how important they may or may not be. Again, maybe it is possible to make them more useful by making them less detailed and higher-level. For example, a flow diagram that shows a pseudocode principle of operation rather than all of the implementation details. Or perhaps two diagrams, to show both the pseudocode (pseudoflow?) and the implementation.

Again, I'm not sure what I would expect to find in an Object Diagram, but I spent a large part of my working life producing flowcharts. I think in the world of multi-threaded code, they get a bit difficult to produce accurately, but I do think that they are useful at the system level. If you look in the Software System Diagram, (https://wmtprojectsforum.altervista.org ... les/Design), you will see what I did very early on to define how the software should deal with the management of the water in the Sump and the (then) Butts. The original of this was produced over four years ago and I don't know how useful Hamish found these when he did the original coding, but they certainly helped me when I was trying to understand what was needed. From a documentation point of view going forward, I think that this sort of diagram would be useful to non-programmers tying to understand the system for maintenance purposes.

I hope that helps.

[PatrickW]

I suppose my reading of the situation is that there is limited time in which to produce some documentation. This may be a misreading.

So, my previous post was musing about possible priorities that might maximise the benefit from the time available. I don't mean to say we the documentation should be restricted to such priorities, or even that they are the right priorities, but they might provide some nutritious, low-hanging fruit.

The problem with only putting the non-obvious terms into a document is that there is no way of knowing what is obvious to new developers going forward (as you've hinted at). The MoD mandated that all terms be included so that this problem never arose. I too thought that this was over the top until one of our Marketeers told me that 'AC' stood for Air Conditioning. You are never completely sure who the audience for a document will be.

Noted. I am in agreement that you cannot assume the audience will understand a seemingly "obvious" term. But I suppose that mandating the inclusion of "all terms" implies having some definition of what constitutes a "term", or some way of recognising when something is, or might be, a term. But I think I am probably overcomplicating this. Maybe it is better to just write a glossary. Deciding which words to add or remove might be a bridge that can be crossed when you come to it.

[hamishmb]

So to summarise:

• Block diagrams seem like a good idea for the big picture overview.
• State machine diagrams (I thought we already had these for your code, Patrick?
• A glossary (specifically for terms used in the software?) is a good idea - but be somewhat selective. We can always remove terms later if they are too obvious/general to be useful.
• For object diagrams I was thinking of showing the structure of the system in memory for a few different pis - eg sump pi is very different to hanham pi. This might not actually be useful though.
• Flow diagrams could show how each of the different threads work - eg the main thread, the sockets thread(s), the monitor thread(s).
• I agree that selective class diagrams would be good, not just doing them for everything. I am not planning to make any big structural or architectural changes again after this final refactor, so they shouldn't go out of date, much.
• In particular, I agree that the class diagrams should just show the relationships between the classes - not worrying overly about multiplicities or methods etc.

Yeah, producing the diagrams before coding is a more traditional way of working (not necessarily obsolete!) but is not how I did it. I'm mostly thinking of what overview-type diagrams might be useful to those who come after us, rather than drilling really far into implementation details.

I think there's plenty of time overall for diagramming, I just won't promise that I will do it at any particular speed as I have numerous other things to be getting on with as well, firstly the refactor and integration and testing of the temporary top up code. I will probably also improve the unit tests and code documentation as I make these changes.

As far as the glossary goes, I think it would be sensible to assume whoever maintains this system after us might not have much experience - I'd err on the side of adding too many terms to the glossary.

Does this all seem reasonable?

NB: I didn't use the flow diagrams when coding, I think Terry might have created them after the coding for the initial system was done.

[hamishmb]

Extra idea: would it be useful to have some extra models that could:

• Show the threads and relevant processes of execution on each different computer, and how they interact at a high level.
• Show how all the different computers interact with each other in a high-level architectural diagram.

These would mostly be useful to those who maintain the software after us I think.

As with the other types of diagram, I'd place an emphasis on getting the main idea across over 100& completeness or getting minute details correct - I think "big picture" diagrams are more likely to be useful.

Another thought: do we have a diagram that shows the structure of the site-wide network and how the computers connect together?

[hamishmb]

I have also noticed that unlike the other projects, we don't have a centralised documentation repo for the river system at: https://gitlab.com/wmtprojectsteam

Shall I create one and include the history of all the documents, should, heaven forbid, this forum go offline someday?

[TerryJC]

Hamish,

That's not strictly true; there is a docs folder at https://gitlab.com/wmtprojectsteam/rive ... aster/docs.

The difference is that prior to this project, I was putting specs etc into gitlab and then we started to used the files area on this server.

[hamishmb]

Ah yes, I forgot about that.

I suppose it doesn't matter, I keep backups of everything on this forum anyway, and I suppose you and Patrick probably also have your own backups.

[hamishmb]

I'm aiming to get started on this very soon, and I will probably start with a glossary. Shall I make a new document for that or do we want it as part of an existing one?