I am an amateur developer and all my programs up to now were simple enough to be documented within the code. While reading the code it was clear what I was doing such and such action (my standard test was to look at the code 6 months later and understand everything at first read – and I have short memory span).
I am now faced with a program which is outgrowing my capacities to remember the various interactions between
- the code itself
- the indexes in the database
- the interactions between various modules ("worker" core code and "library" ones)
My current documentation is a whiteboard where I have all kind of boxes and arrows which point to code, to database indexes, to actions being executed, to state change etc. Just for reference, a fragment of the mess:
My question is whether there is a standard, or named set of best practices (named in the sense that this is a set of practices which were grouped under a specific name) for the documentation of more complex products.
What are the keywords I should look for (general attempts at "document software architecture standards" and similar variations usually led to software for workflows or building architecture CAD systems).
I also expect that there may be no general best practices for high-level descriptions and that everyone builds its own philosophy.
Best Answer
There isn't one standard that everyone adheres to. Software projects can vary greatly (think: helloworld.py vs the code in the space shuttle).
One very common method is to use the 4+1 model. Instead of trying to cram everything into a single style of document, this methodology breaks the design into five components:
The various views describe the product from four different perspectives. The scenarios are where the use cases live, and describe the interaction of the other views.
Note: This is a conceptual model, and is not tied to any specific tool.
You can read more here: