Importance of documentation in choosing the right technology
As a software developer, I often have to choose between different libraries or stacks to build upon. Often there are so many different options available, that one cannot evaluate all the options thoroughly. And even if I could evaluate them all, I would still have a problem with assigning optimal weights to different aspects like code readability, performance, amount of dependencies, stability etc. So, I need to rely on heuristics. But what are the good heuristics that one should use?
I would argue that one of the most important heuristics for choosing a technology is the quality of documentation. Well-written documentation makes using the software easy and productive. Poor or missing documentation greatly increases the time needed to make use of a library and sometimes there can be subtle mistakes, that arise because the documentation is vague.
When everything else seems roughly equivalent, I will choose the more popular option, but popularity is not the best gauge for other aspects. A good example of that can be seen in the following quick writeup about NodeJs libraries, where the main point is that blindly following others based on GitHub stars is not a good advice, when you also care about performance.
About keeping manuals under NDA
In the electronics industry it is very common that data sheets for specialized chips are available only after signing a Non-Disclosure-Agreement. That means, you can buy the chip, but have no clue on how to actually program and use it. Companies who order large batches usually get the documentation and the support they need, but individual hobbyist are left in the dark.
Sometimes the documentation is never released. A problem that should be familiar to a larger audience is the lack of proper free and open source video card drivers for Nvidia graphics cards on Linux. Thanks to the reverse engineering, there is the open source Nouveau driver, but it is still not as good as the proprietary drivers.
Similarly, one chip in particular with which I personally have had problems is the InvenSense MPU-6050. This is a relatively cheap sensor, that has an integrated 3-axis gyroscope and a 3-axis accelerometer. In addition to this, it can control another I2C slave device and has a “Digital Motion Processor (DMP)”. The DMP can be used to do calculation on the chip directly to offload processing from the host application processor. For an example the MPU-6050 can be used as an Inertial Measurement Unit with DMP doing the calculations or the DMP can be used for gesture recognition. However, there is no publicly available information about the DMP, so half of the MPU-6050 is somewhat unusable. There are captured and reverse engineered firmware blobs available for the DMP, but when you want to make use of custom algorithms or external sensors you have no idea how to program the DMP yourself.
Linux folks with FOSS in their heart tend to buy AMD graphics cards instead of Nvidia, which means less Nvidia hardware sold because lack of documentation makes writing FOSS drivers hard. In the case of MPU-6050, if DMP’s documentation was available, a novel application for the chip could be found by tinkerers and the sensor might go into a new popular device. That would mean much more sales for InvenSense.
Developer Zone
This shows why documentation is important and why it is bad to keep documentation closed or behind an NDA. We, the Sharemind team, had some manuals and materials available, but they were given out on a need to know basis and were scattered in different places. That situation was suboptimal for someone who looks at our main website, becomes a little interested and wants to learn more without actually contacting us. High-level overviews on our website are good, but technical people also want to take a glance at the API to have a better understanding of the software and to distinguish concrete software from vaporware.
To remedy the situation, we introduce you to the Sharemind Developer Zone. On that site, we have put together and made freely available a lot of materials. It has an overview of the Sharemind technology, installation manuals, tutorials and API descriptions.
The Developer Zone is still a work in progress, we are constantly working on improving it with added contents like more tutorials and example projects. In the future we might also add a module for community provided content like a forum or a Q/A section. At the moment the documentation is Sharemind MPC specific, but in time, as the developer tools of Sharemind HI improve, they will also be included in the Developer Zone.
