Advent of Technical Writing: Reviewing the Wolfram Language Documentation

This is the eighteenth post in the Advent of Technical Writing series, wherein I will share something I have learned from my experience as a technical writer. My experience is primarily in software technical writing, but what you read may apply to different fields, too. View all posts in the series.

Earlier this year, I was exploring Wolfram Language, a programming language grounded in knowledge. I am fascinated by the "notebook" environment of working, in which you write instructions and receive results from them in an interactive environment, among many other parts of the language. As part of my learning, I referred to the Wolfram Language documentation, which is now one of my favourite examples of well-written technical documentation.

Consider the InputField page in the Wolfram Language documentation. This page describes InputField, part of the language. Above the fold, there is a big box that shows all of the ways in which you can use InputField with its supported arguments. Each syntax variation has a clear definition. Skimming the top of this page, I can already see six ways I could use the InputField method.

Scrolling down further, I can seek more information. The "Details and Options" section contains easy-to-skim information about using InputField. The bullet point presentation makes each point stand out. This structure makes sense because every point is a distinct piece of information about the InputField function.

Then, I can see usage examples. Whereas the start of the page featured the language reference with what you can do with InputField, the examples section shows the function in action. The page succinctly shows examples of an input and the corresponding output from each example. There are more reference examples, but these are conveniently hidden behind accordions with the names of each documented attribute.

Reading over the page, it is clear the Wolfram team have thought a lot about what is necessary and highlighted that information prominently. Looking at this page as a novice to the language, I feel like the page is easy to navigate. I don't feel intimidated by information overload. Specialist options -- which may need to be referred to by someone, but not most users -- is hidden in accordions. In my usage of the wiki, I have seldom expanded the accordions.

Then, the page ends with links to more relevant pages. These pages link out to other language reference pages and useful guides. These features are a great way to explore the language and learn about new features. For example, when I was learning about the natural language processing capabilities in Wolfram Language I spent a bit of time clicking around to see what was possible. Wolfram made such exploration easy.

At the top of the page, there is a search bar with which I can find information. Of note, the "Wolfram Language Documentation" search results feature direct, one-sentence descriptions of the contents of each resource. This makes it easy to evaluate whether a page is relevant to my query without having to click through to a new page.

Overall, Wolfram's documentation is easy to read, well-linked (which enables greater exploration), and feels more approachable than many documentation sites I have visited. Their choice to hide some information behind an accordion is inspiring. I love the pattern. Technical documentation should be written with common use cases in mind. Documenting every detail in a library or programming language is useful, but advanced options that are unlikely to be used by most users should be less prominent on the page. This is the case with the Wolfram Language documentation.

Join me tomorrow for another blog post in the Advent of Technical Writing series.