RT-Thread conference: the problem with the documentation
Last week, we participated in the RT-Thread conference to teach engineers about issues with poorly written documentation and APIs. Why is well-documented code important, how can poorly written APIs present challenges, and what can engineers do to help others?
Does the engineering community have a problem with poor documentation?
Unless a project, device or software is used by a single person, it is essential that any associated documentation is well written, clearly presented and conforms to a set of publishing standards. Some may think extensive documentation is too laborious or unnecessary and so write short descriptions of code functions, provide minimal product drawings, or use abbreviations and abbreviated descriptors.
However, the sole purpose of the documentation is to educate others not involved in the initial design and development. As long as the reader has the minimum skills required (such as an understanding of C code, how to design electronic circuits, or use CAD), the documentation should provide the means to fully understand how a system works and offer a range of examples. if necessary.
Unfortunately, large amounts of poor documentation, confusing API names, and overly complicated examples are found in modern designs and platforms. While not a problem for engineers with years of experience in a particular field, those looking to explore new areas can quickly find themselves confused, frustrated, and dissuaded from pursuing a project.
The common theme between engineers and documentation is that engineers write documentation from their point of view and assume that the reader has the same level of knowledge. Why this is the case is unclear; it could be due to laziness, it could be due to lack of empathy for the reader, it could be the difficulty and time spent writing well-written documentation, or it could be a trait found in those from academia (mathematicians are notorious for this).
Whatever the reason, the examples and documentation provided by engineers can often be poorly written, which is often a roadblock for those looking to explore advanced topics and designs.
It’s not just documentation; APIs can often be confusing
The documentation used to describe code functions, describe component metrics, or show examples aren’t the only aspects of engineering that often receive little attention; Code APIs can also be unusual and misnamed. To understand why it’s important to have clear function names for an API, we first need to look back in time and understand why high-level languages arose.
Early computer systems had limited resources in processing capacity and memory size. As such, every byte of memory used and every microsecond of execution time consumed had to be carefully accounted for. In such cases, assembly language coding allows engineers to design applications at the instruction level, allowing each instruction to be queried.
Should we use two bytes to load register A with zero, or should we use an XOR A instruction to reset the register and use only one byte? Should all strings be zero-terminated, or should we save the bytes and specifically pass string lengths to string print functions? Should we use a register to hold a loop counter and execute a piece of code n times, or should the loop be unrolled to reduce the execution time of loop counter updates and jumps? These are just a tiny fraction of the coding tricks engineers would use to maximize application speed and minimize memory usage.
However, as computing resources increased, the complexity of applications also increased, and trying to code complex programs in pure assembler was difficult and time-consuming. Combined with increasing system resources, high-level languages quickly became dominant in the field of computer engineering with examples such as C, C++, Python, and Java. These languages allow for a large amount of abstraction that hides the inner workings of a computer program while providing advanced features such as dynamic memory management, function calling, object-oriented programming, and commonly used routines.
But above all, high-level languages allow code to be much more readable through the use of function names that make sense and more readable code. For example, a Z80 for loop assembler would use register B and register DJNZ to loop until register B is zero, but a C application can simply use the term “for(I = 0; I
So, given that high-level languages allow easy-to-read functions and code layout, it’s amazing how APIs are written by engineers who use bad naming conventions. For example, the term kprintf is often used to refer to printing text to the kernel debug console, but it would make much more sense if the name kernel_print was used instead. Another example is dfs_mkdr which is used to create a new directory in a virtual filesystem, but a better name would be dfs_createDirectory or fileSys_createDirectory.
Some would argue that the specific usage of mkdr originated from older established Unix systems, but just because older computer systems used shorthand naming conventions (due to memory limitations) doesn’t mean they should continue to be used.
How can engineers help others?
To really understand what the documentation and APIs should look like, just turn to the Arduino platform or the Blues Wireless Notecard tutorials.
The Arduino platform not only uses well-defined API wrappers whose name clearly refers to their function, but online tutorials and examples are more or less complex, with the most basic examples using only the strict minimum code needed and the most complex examples including all aspects. of an API. Also, the functions described in the online documentation don’t just show the name of the function and the parameters it takes. And it also provides several code examples to show how they work and the expected results they give.
Blues Wireless is another example of excellent documentation and examples. Not only is their online documentation well presented using modern graphics, but the website also provides clear examples that can be copied and pasted to their note cards via USB to serial connection. Additionally, their site also incorporates a serial terminal that can connect to the Notecard, allowing examples from the documentation to be run directly in the browser.
What engineers can learn from these examples is that when writing documentation, it should be done from the perspective of the reader, not the author. Additionally, engineers who write tutorials and examples need to move from the most abstract to the most complex code. For example, resources that teach an RTOS should not begin by describing how processes are handled by the kernel or how memory is allocated, but rather should begin with a trivial example of LED blinking that demonstrates how to include the system of exploitation, how to launch it and add a task that makes the LED blink.
Ultimately, writing clear documentation that guides the reader through a journey will be greatly appreciated by others and will also help future engineers who may need to outgrow a project if the original engineers left. .