Recently I have been involved in, or more appropriately "struggling with", the conversion (port) of a Windows-based threading toolkit to Linux. This port is a work in progress and is now in Alpha test. The port should have been relatively straightforward to implement, and will likely be easy to implement the second time it is re-implemented.

What makes this port particularly difficult is not the functional design of the software, nor in the execution of the functional design into a well working set of source code designed for a specific platform. In this case the working software runs well on Windows x32 and x64. The difficult part is finding well-written documentation that distills most of what you need to know about an API into a single reference source.

This writer's programming background goes back to the late 1960s and I have witnessed most of the evolution of software development, the tools used, and the accompanying documentation. I have authored many software tools and the accompanying documentation.

As the evolution progressed in compilers (languages and dialects), run-time libraries and operating systems a class of tools was developed to aid in documenting computer software. Initially these tools did little more than pagination. Later, came the features of: titles, subtitles, formatting, different fonts, auto-generation of Table of Contents, and auto-gen of Indexes. Some of today's documentation tools go further to the point of if you comment and annotate your source code properly, that the document authoring tool can use these comments and annotations to produce a reasonably good rough draft, or more appropriately stated, outline for your documentation.

The problem, as observed by this writer, is the documentation writers do not "flesh out" the auto-generated document outline. The end result, from my perspective, is a compendium of function prototypes and an incomplete set of hyperlinks to related function prototypes. This lack of a comprehensive documentation is the cause for an inordinate number of hours in lost productivity.

As an example of this, I will choose a common general programming function from the C runtime library. My gripe is not particularly with this function, I do not need someone to explain this function to me. Rather the manner in which this function is currently documented is symptomatic of the subject of this article. The function chosen for this example is the file I/O open statement.

The following is from http://www.gnu.org/s/libc/manual/html_node/Opening-and-Closing-Files.html#index-open-1200.

---

---

The problem I have with the above documentation is, that above is not a comprehensive reference as to how to use this function.

For comparison purposes, let's look at what I would consider comprehensive documentation of the open function API. The source of this documentation is from the Borland C++ Version 3.0 Library Reference, Copyright 1991 by Borland International, pages 377-379.

---

---

---

---

---

---

What I find particularly useful in the Borland documentation, and sorely lacking in the gnu.org documentation, is that Borland consolidates virtually everything you need to know about this function into this section of the document. This includes:

1. The/all #include file list as would appear in your application

2. function prototype

3. compatibility table

4. sample of the function call

5. list of and description of the required access flags

6. list of and description of the optional access flags

7. list of and description of the mode flags used when creating a file

8. a list of return values

9. a list of related library functions

10. a complete working example program using the function.

By contrast, the gnu documentation has:

1. mentions a required header, but not all required headers, and does not show an example #include as it would in your application (in the event the header is located off a different path)

2. function prototype

8. a list of return values

Missing are 3, 4, 5, 6, 7, 9, and 10.

These missing sections in the gnu reference require the reader to have multiple pages of the reference document open concurrently and mentally fused together to present the reader with the equivalent reference as presented in a nearly 20-year old reference manual.

Although this blog may seem that I am unfairly picking on gnu.org contributors of their work in writing their documents, I wish to state my intentions are more towards gentle prodding to do better. Good documentation leads to better code writing and faster assimilation of knowledge.