As to be expected from any technical project that matters to anyone, I received valuable comments on the technical solution I shared a week ago about the RFID network of a makerspace.
More than a final technical solution, that post was more of a draft, acknowledging the likelihood of mistakes and recognizing it wasn’t up to true engineering standards.
However, it was a good starting point to begin the conversation about how we want to manage the space.
In this article, I will organize my thoughts on executing this documentation process by delving into the production and structure of a technical document.
Moreover, I’ll illustrate these principles by presenting a new technical solution in a separate pice of content.
The aim is to showcase how the discussed process translates into practical application, offering insights into creating documentation that is trully useful.
I have come to understand that the creation of any kind of document whether technical or creative in nature is not a standalone task but the culmination of a well-defined process.
In the realm of technical documentation, this process is particularly crucial for ensuring clarity, precision, and effective communication.
The ultimate purpose of this ongoing process is to empower all technical contributors to engage in productive and aligned discussions over concrete dimensions of a system.
Additional advantages involve increased speed of onboarding for new team members and more precise descriptions about the state of a project.
By examining concrete dimensions of a system, our ultimate goal is to enable productive discussions among all technical contributors to a project.
Some of the feedback I received from the last article involved issues with its structure and its content.
The following is a list of bullet points of what to expect from one of those documents for future reference.
There are some interesting templates made by Uber and other large companies to structure their technical proposals and documentation.
They have their own processes on how to achieve this that I will surely try to replicate in the future.
I received feedback of multiple mistakes on the article, both regarding the way I express myself in english and just plain typos.
Given that I am using a simple text editor to write these articles and that I am not a native speaker this was to be expected but not an excuse.
To solve the grammar mistakes and provide simple sugestions I have been using languagetool.
It is a pretty good open source solution that can be integrated in the browser and also used as a self-contained CLI application that I recommend to any non-native english speaker.
There are other levels to writting and language nuances that can only be pointed out by a native speaker. Unfourtunately, I have no easy access to such people due to the fact that I live in a spanish-speaking country with spanish-speaking problems regarding the english language.
For these kinds of spelling mistakes or imprecissions I have found LLMs such as ChatGPT of great help for providing excellent sugestions to express my ideas in a clearer manner.
Another advantage of getting assited by an LLM is that it will provide imparcial and practical feedback about the ideas you are working with, while your peers and friends might not be able to provide such feedback for a variety of reasons such as time availability or lack of knowledge.
Looking ahead, I believe that multinational working environments will greatly benefit from the power of these models once they are fully deployed in knowledge management tools.
However, I believe that the privacy of those recommendations will be never be guaranteed unless self-hosting the LLMs for your own organization becomes a viable solution.
If the document is going to be publicly available, so I do not have any issues with OpenAI using the information on my queries for this kind of public work.
However, the first reviewer is always the writer and most language issues can be found and solved by simply reading the article multiple times.
We use different criteria when we write a document for clarifying our ideas such as the ones in a notebook or communicating them to peers and friends.
Both criterias have value and their place in the process of producing high quality software or working with ideas in general.
You want to have good and useful notes to remember details and information only you will read, or to work through a process by yourself.
But notes and drafts are not good enought for communicating technical information unless the reader has a very similar thought process, is highly informed in the context of the document and belongs to the same culture as the writter.
While this is a blog and the purpose of a blog depends purely on the intent of the writer, the intent of that particular article was communication.
However, I wrote it for clarifying my own ideas, which is needed and necessary but not enough for communicating them nor a professional project implementation.
When writting for other people, we must first have a good understanding about who will spend the time and energy of reading a document in an age of decreasing attention spans and LLMs that will summarize anything you provide them into a set of bullet points.
This means that you need to understand your audience, adapt your language to their technical expertise and familiarity with the subject.
You also need to define what needs to be transmitted and the outcome it needs to produce in your readership.
Another thing I missed was to provide enought non-trivial context about the state of the space such as the existing network architecture and how we want it to be used.
When asked for advice, I find myself with the problem of not having enought information in order to make an accurate assesment of the situation and thus provide a useful answer.
By providing enought context, we want to precisely avoid that for our audience.
This is a key difference between writting for myself and writting for others.
To be conscious of the fact that other people do not have access to the information I might be aware of and being able to identify which of that context is needed beforehand.
The need for an RFID access control mechanism is not a straighforward decision, it comes with some assumptions and an intent that should have been stated in the technical proposal.
Next, the document should clearly outline key objectives, the information that needs to be transmitted across or the issues that need discussion and consensus.
A document such as this one should be written in a way that it only needs to be read once in order to understand:
From the pragmatic engineer blog we can shamelessly derive the following generic template.
In the end, such a template must change according to what the organization cares about.
Summarizing walls of text and code segments into diagrams helps the reader to leverage the visual cortex we have evolved with as humans.
This is by no means new in engineering disciplines, computer engineering might be the only discipline that has allowed itself to maintain projects that do not have good descriptions of what has been built appart from the code.
A fast review of UML and ER diagrams can be found here.
We can see from this fast reviews that there are two kinds of diagrams:
What this tells me is that diagrams are not in some final step of the design process but need to be integrated, mutated, changed through it and probably completely reworked at some point until they reach a final stage.
The next question here would be when do you stop? When is the design good enough?
These are all good questions, and the answer might be in the dark watters of experience. Criteria that we can use is that a diagram is ready when it is useful and not wrong given the knowledge currently available.
In more mathematical terms, a diagram should map to a statement or algorithm that is logically correct given the requirements of the solution and the stated preconditions of the problem to be solved.
However, this is hard to achieve, so in the end we end up with a diagram or a system description that is good enough given the current level of knowledge and experience we have with the system.
At this point we should decide if we can get to the next step of the process without hitting any inconsistencies or edge cases.
Any diagrams used should be able to be self-explainatory once the text has been read once.
In my technical solution, I used PlantUML for defining a couple of UML diagrams that were non-standard. The diagrams given by PlantUML are also pretty suboptimal in the aesthetic sense, and I was recommended to use mermaid.js instead.
Although this helped me clarify my ideas, those diagrams were misunderstood by the readers and were insufficient for explaining the protocol I had devised for the system. I should have used sequence diagrams in order to expose the protocol between the nodes of a system.
This would have given me a framework to play out different situations that would have revealed its flaws. This what a deep review would look like.
I probably did not provide enought context for the understanding of those diagrams or entered into too much detail.
Instead of the use case analysis, I jumped right into the architecture description and should have defined the use cases before having a particular architecture in mind.
The C4 model for visualising software architecture was also confused as an architectural style instead of a framework for description of analysis.
I blame of familiarity for this one and the fact that the creator of this model gave such bad names for its abstractions (“containers” in C4 are not Docker containers).
However, I think this model can still be a good tool to describe the architecture of a solution, although not good enough to model desired behavior.
I also got too soon into the definition of the data model, which is highly coupled with the tecnologies of the solution itself.
In general, I think I should have put more attention to detail in the diagrams I included.
Software is hard, it requires discipline, focus, knowledge and planning.
It also requires collaboration which is only possible with good communication between everyone involved.
Hopefully you have learned as much from this article as I have writting it so that we will both make better technical plans for the future.
Jaime Romero is a software developer and cybersecurity expert operating in Western Europe.