Communication is essential to the enterprise of knowledge. Without communication, we would never be able to build upon the works of others or have them build upon our own. One of the most important – and challenging – arts within communication is writing. Writing is unique among commutative forms in its durability and portability. Once written, the words of the author can transcend even their death and travel places they never dreamed to tread. However writings portability and durability are the same feature that present its central challenge: With the author long gone, how can the he still communicate his or her intent? In this post, I ponder how I face these challenges and encourage others to do the same.

In short, the best papers: write with a purpose, recognize every technical document is persuasive, do not neglect the importance of structure, and are written for the public.

Write with a purpose

Before writing it is essential to consider your purpose. Your purpose will determine many aspects about how you write.

For example, the purpose of these blog posts is to save me time.

How can writing save time? From time to time, my classmates and others ask me questions. Often time the first and second time, I give a response, but by the time that I get the same question three times, I add the question to the list of topics for these posts. Then when the post is written, I can then give these posts to anyone else who inquires and use it as a starting place for discussion.

Given this purpose, it informs how I write. I need to be comprehensive if I want the post to actually save me time; however if the posts are too long, they never will be read. The way that I attempt to make this compromise is by providing extensive references rather than the inlining them into the text itself. That way the interested party can investigate only the topics of greatest interest, and the lackadaisical one can simply skim on.

When writing I often consider, “how can I increase the signal to noise ratio for my audience?” The higher this ratio, the better investment reading it is for them. The better investment it is for them, the more likely they are to use it.

If they don’t care about something, it shouldn’t be included. This manifests itself in several ways: Some audiences don’t care about details and an endless slog of details makes a text unapproachable and a waste of their time and attention. Even engaged audiences don’t care about everything. Is what I have written going to help them do their job, help them teach this to others, or help them enjoy the text? Therefore, I write with a presumption of apathy and find something useful only when I can reasonably are interesting to the audience. “tl;dr” – too long didn’t read – is a reality and I fear a common one.

Recognize every technical document is persuasive

A corollary to writing with a purpose is that every non-fiction document is persuasive. Informative writing attempts to persuade the reader of the truth of certain facts; proposals are attempt to persuade the reader of value of an idea. Something as simple as a receipt is attempting to persuade its reader that the holder has obtained a good or service. Even “objective” writing that desires to show various sides of an argument argues at a minimum that they are presenting each viewpoint accurately. The author’s purpose at some fundamental level is to persuade of some truth.

So what does this mean for writing? If every document is persuasive, then every document has an argument. Making this argument as clear as possible improves the writing in several ways:

First, it makes it easier to spot flaws in the reasoning of the argument. These flaws, called fallacies, devastate the integrity of your arguments and perhaps your own as well. Identifying them in your writing and those of your sources preempts possible objections.

What about the counter-claim that not every truth claim can be accessed by logic? While it is true that you may not be able to present a definitive logical argument for every situation, you can almost always make a case on the plurality of the evidence – an inference to the best explanation.

Second, well reasoned papers are easier to follow. A well reasoned paper, has a inherent structure – namely its argument – that makes it easier for the reader to follow. Immanuel Kant called this structure a schema in his work “Critique of Pure Reason”. Since then others such as Jean Piaget in his work “Origins of Intelligence in Children” have argued that schema are critical to the formation of idea and cognitive development .

Finally, it makes it easier to identify irrelevant sections of your writing. If a statement or section does not contribute to the overall argument of the piece, it should be discarded.

However, even the clearest writing lacking support is unlikely to garner assent. This means that conclusions, motives, and methods are equally important. An unsupported argument is often as useful as an unmade one. Here are some common mistakes that I have seen:

• Not describing the methods in sufficient detail to replicate them. Describing methods is the “showing your work” from your high-school math class. Yes, eventually you can show progressively less and less work as you get a more sophisticated audience, but if the audience could and wanted to completely do these work of proving your point themselves, they wouldn’t be reading your paper. This also helps you identify methodological flaws in your work before they are written as criticism because it forces you to reckon with your methods and their methods.
• Not justifying the reasons for your methods. Nearly all experiments have some number of arbitrary choices. However, there can be great significance in which choices were arbitrary and which were informed. Explaining to your audience which is which is one of the few ways they know the difference.
• Conclusions must follow logically from the arguments. Often in my primary education, I heard it described that conclusions ought to summarize the essay followed. I submit this is insufficient. Conclusions need to explicitly and logically follow from that which came before. Otherwise, what is it concluding?

• What is the purpose of your document? What is the argument presented by your document? Does the argument support your purpose or is their missing or extraneous information?

Using Evidence

Arguments are evaluated by the evidences for them. As the writer, you choose what evidence you present and how you present it. While evidence fundamentally boils down to a series of a series of premises, how you present these premises can effect the credence that the reader assigns to them and their ability to quickly digest the information. When writing academic papers, there are several common ways that you can present evidence:

As the writer, you have a fixed (and unknown) budget of attention from your reader. Your goal is to provide the most benefit to the arguments that you believe the reader will want the most support for within that budget. Things like tables, figures, and mathematical models can go a long way to convince your reader that your argument is accurate, but take substantial space on the page and for the reader to consume them. Things like citations and inline evidence provide little benefit on their own – most reviewers do not follow references in my experience and may not take evidence presented at face value, but can be expressed quickly. While these values of benefit and space are subjective and differ from discipline to discipline, they can be indicative of how much people may pay attention to the evidence they present.

One method though bears special attention, “hand waving”. Hand waving leaves an aspect of your argument for the reader to supply the argument on their own. This is free, you don’t have to write anything thus saving on your attention budget, but comes with substantial risk the reader will doubt it having no evidence. Another place where hand waving is used is when you want to ignore a orthogonal concern or something you expect the reader to know. How effective this is depends greatly on whether your audience agrees with you that the concern is truly orthogonal or is aware of it. For this reason, I have a love-hate relation with hand waving, you can’t restate everything on a topic every time, but also don’t want to inadequately support your argument either

• For your argument, what pierces of evidence do you have? What format(s) are appropriate for each aspect of your argument?

Do not neglect the importance of structure

Just as important as logical structure, physical structure is also key. The physical structure of writing should make easy for the reader to find what they care about. Making information easy to find takes many forms:

It means putting the information the reader cares about earlier in the document. Every additional sentence, reduces the chances your reader is paying careful attention when they get to the end. How is this different from identifying the logical structure and eliminating irrelevant details? Consider the classical argument:

A. Socrates is a man
B. All men are mortal
C. Therefore, Socrates is mortal

There are 6 possible arrangements of this argument that are all equally logical valid. Not all 6 of these arrangements are equally comprehensible. It generally makes sense that conclusions (part C) ought to follow after the premises (parts A and B). However, there are still two possible arrangements of parts A and B if C is to go last. Putting the argument that the reader cares about first can help them find the information the care about more quickly.

It can also mean the formatting and typesetting of a document. Headings, bold, and italics help reduce the homogeneity of your text giving the reader something to easily find their way back to if their eyes or mind drift. However, too much formatting can distract the reader. Remember the example of a book in which everything is highlighted: when everything is highlighted, nothing is effectively highlighted.

Structure includes grammar. While perfect grammar is seldom necessary, careless grammar can be distracting – or worse confusing. Everyone should have and use a grammatical reference; I recommend Strunk and White’s Elements of Style.

Finally for longer texts, a good index, table of contents, and glossary can also make a difference. They allow a narrowly interested reader to jump directly to a topic of interest rather than having read everything.

Do indexes still make sense in the age of electronic documents and search functionality? I think so, but the threshold for a good index has risen. No longer is it sufficient to identify the locations of key terms, indexes now should help the reader determine the passages where a topic is most directly addressed and where related topics are. For example:

tasks 1
    User 1
    Kernel 2,3
    OpenMP 27-30
    MPI 31-35
    Hadoop  70-72

This index shows that tasks exist for users, the kernel, OpenMP, MPI, and Hadoop. Yes, the user could search for each of these terms independently, words like “user” are likely often used all over the document. Providing an index can help the reader find the instances that are actually useful to them.

• What structuring of your argument is most consistent and logical? How does the ordering of points impact the strength of your argument?

Consider Writing for the public

Far too often, I read a paper in my own field that has so much mathematical notation or technical jargon and find myself questioning what it even meant. You never know who will read your paper or why. You will never know what context they are coming from. For this reason, one should always try to make their paper more approachable to the general public. It opens your work to people who may be interested in your topic, but currently lack expertise. It also makes it easier for experienced readers to quickly understand and appreciate your work.

This manifests itself in several concrete suggestions:

• Try to appeal to universal examples. Taking all of your examples from a signal domain reduces the portability of your writing across domains. Don’t assume the reader knows the specific name for a concept or example you use. Describe each briefly just in case an someone outside your intended audience reads your paper.
• Avoid unnecessary notation and terminology. Notion and terminology are powerful in that they allow us to allow us to concisely represent a specific concept. However, the average human brain can only manage 7±2 things at a time. Each term that the author introduces increases the required mental bandwidth to understand the paper.
• If you use notation and terminology, use it consistently. Inconsistent notation not only can pollute the brains name space for notation wasting one of the 7 scarce places for temporary storage, but it also can lead to ambiguities in your argument which lead to misunderstanding.
• Consider the importance of abstractions. Remember the brain has limited short term storage. Abstractions allow the reader to fit multiple related items the same unit of working memory. Good abstractions are concise, coherent, and extensible. In my opinion, there is substantial overlap between creating good object-oriented designs and creating good abstractions. I would read the short article “Principles of OOD” by Robert Martin on object oriented design for some of the principles to consider.
• Make your work self-contained. A key tool to make a paper self contained is to include background and related works sections. A good background section allows the general public to have a sufficient understanding of your topic to understand your writing. In contrast, related work exists exists to demonstrate the distinctiveness of a work relative to its competitors.

• How can you adapt your writing to improve how you write for the public?

Writing a Learning to Learn

Let’s look how I try to apply advice to write a “Learning to Learn” post. Here is the outline that I start with when writing a learning to learn post for a technology:

1. How do you get started? This is where I highlight the resources I recommend for true beginners to the topic, and perhaps the field in general.
2. What are the important tools and utilities to know about?
   1. What are the most important Standard/Included features? Here I try to make recommendations about what parts of the technology are worth prioritizing learning
   2. What are the important 3rd party libraries? Most tools/technologies leave some aspects of their systems to 3rd parties to implement. Here I try to summarize which 3rd part libraries/plugins one should encourage someone to adopt this technology or accomplish basic tasks left out of the standard functionality.
   3. Tools that make using the technology better? Here is where I summarize things that operate on the language or tool rather than extend it. The classic example would be a debugger or a profiler for a programming language. You likely won’t use a debugger from the language itself, but it’s an invaluable tool to learn to use it.
   4. Tools made better by using this technology. Some tools can be extended via use of a given technology. A clear example of this would be python extensions for GDB. Here I try to highlight some of these kinds of synergies.
3. What are the important concepts? Here I try to summarize the concepts that are so important, that I feel they are worth a paragraph or two of dedicated discussion.
4. What topics should I read more about, but aren’t really an introductory topic? Here I try to list important topics that a beginner or intermediate user doesn’t need to know to get started, but should learn to become more advanced.
5. Where can I go for more information? Lastly I try to highlight some resources that I use for more advanced or complete information on a topic.

That doesn’t mean that I stick exclusively to this outline. For example, C++ doesn’t have section 2.4 because in my opinion writing dynamically loaded library extensions isn’t a feature most programmers are going to use, and is tricky to get write correctly. I also feel free to add additional sections as I feel they are important. For example the Linux post spends a lot of time discussing how to get software and choose a distribution rather than provide a general overview of how to use it. That’s because I’m not convinced the best way to get started learning Linux is going to remain stable long enough for this kind of post to remain useful. Instead I try to point users to more important meta questions about how to adapt to changes and find new work flows.

Changelog

• February 2023 - Added section on using evidence
• August 2020 - Added section on writing a learning to learn

Hope this helps!