Crafting Exceptional Documentation: A Comprehensive Guide
Written on
Introduction
For those familiar with my Medium blog, you may know that I have been developing a web framework using Julia for some time now. The project is progressing well, and as it nears a stage where others might begin utilizing it, I find it essential to evaluate the quality of its documentation. A common challenge in creating effective documentation is that authors often possess a deep understanding of the subject matter, which can lead to a disconnect with users who are not as familiar.
Nevertheless, there are effective strategies to mitigate this issue when documenting software. One approach that has proven beneficial in my experience is adhering to certain guidelines that ensure documentation is not only comprehensive but also presented consistently. Today, I want to share some of the techniques I’ve implemented while documenting my web framework, as I have dedicated considerable effort to making it user-friendly and understandable.
Consistency
A key aspect I want to emphasize, which is often overlooked in documentation, is the importance of consistency. Effective documentation requires a uniform approach! The rationale behind this is that users are already inundated with new information about your package; therefore, introducing numerous formats for docstrings can be overwhelming.
Moreover, aligning with the documentation conventions of your programming language is crucial. For Julia, we can refer to its base documentation to gather prominent examples of standard practices. However, I do have some critiques regarding certain docstrings.
In some respects, this docstring is exemplary. It is informative, offering a thorough description along with all necessary constructors and their arguments. However, it might surprise you to learn that String is a subtype of AbstractString — String <: AbstractString. Given that you are reviewing a docstring for String, you may also wish to explore its field names. Fortunately, in this case, String is straightforward, but many of Julia's base types can be more complex. Additionally, the absence of examples for the String constructor is notable, especially since many users will learn by copying and pasting examples, which is especially true for newcomers.
In many instances, it is understandable that the documentation for strings may not be optimal, as they are typically constructed through methods and string delimiters. Nevertheless, Julia excels in its documentation for methods:
The push! docstring serves as an excellent example of effective documentation. It is applicable across a wide range of Julia Base types, with names that reflect its general nature. This docstring also includes an example, similar methods, and a concise description.
Julia's base documentation maintains a level of consistency that is commendable, making it easier to read the docstring for contains after having reviewed the one for push:
Both of these docstrings provide information on arguments and return values, which greatly aids in understanding how to utilize the documentation. I highlight Julia's base documentation as a good benchmark because it offers consistency that can be applied in our documentation for Julia projects, ensuring that users can quickly recognize our format and navigate it effectively.
Let's create a docstring!
Including Examples
Another essential practice is to incorporate examples. Examples effectively illustrate the expected inputs and outputs for a given function. They can showcase dummy data that is shaped correctly for the function, helping to clarify different syntax nuances through various usage scenarios.
Furthermore, examples significantly enhance accessibility for new users. From my own experiences and those of peers, examples are crucial for teaching programming. They allow someone to see a functioning method call, which they can then adapt for their specific needs.
x = "px"
y = 50
myfunc(x, y)
"50px"
Input and Output
Input and output specifications are also vital in function documentation. In many traditional applications, such as Assembly language documentation, it is common to provide only a brief description unless the function name is insufficiently descriptive, along with clear input and output details. Often, these elements can be the focal point of documentation, especially for experienced programmers looking for quick references.
Consistency in documenting inputs and outputs is particularly important. Julia employs a structured approach to outline these aspects, typically formatting functions similarly to anonymous functions.
myfunc(x::String, y::Integer) -> ::String
x = "px"
y = 50
myfunc(x, y)
"50px"
Argument Names
Ensuring that argument names in documentation align with their data representations is also crucial. Maintaining uniformity across all code enhances clarity for developers interacting with your documentation. This principle should extend to function names as well.
To explore more on this topic, I previously wrote an article discussing less-obvious yet impactful factors that contribute to quality code.
Defining Type Consistencies
It is also beneficial to clarify any type consistencies that users might encounter. Many contemporary programming languages leverage inheritance, which can reduce the need for multiple functions. In Julia, types are organized hierarchically, encompassing both concrete types and abstract groupings. Below is an example of an abstract type in Julia from my web framework that illustrates the relationships between its subtypes:
Fields/Attributes
When documenting a type, it is advisable to include its fields or attributes, along with clear descriptions. Below is an example of well-documented fields from Toolips in the form of ServerTemplate:
Conclusion
While our example method may lack a super-type and fields, the docstring remains informative and engaging!
iwith_suffix(suffix::String, number::Integer) -> ::String
suffix = "px"
number = 50
myfunc(suffix, number)
"50px"
Documentation plays a critical role in the usability of your code. Regardless of the quality of your code, without effective documentation, it can be challenging for others to utilize it, especially in environments with package managers where users may never directly engage with the code itself.
I appreciate your time in reading this, and I hope that implementing these valuable tips will enhance your documentation efforts! With practice, writing documentation can become an enjoyable and fulfilling task. Thank you for exploring my article, and happy documenting!
The first video titled "10 Best Practices for Writing Documentation" by Lauren Schaefer discusses effective strategies for crafting clear and helpful documentation.
The second video, "How to Document Your Code Like a Pro," provides insights into professional documentation techniques that enhance code usability.