Originally published here
Why does this matter?
I'm currently studying Computer Science among other things at university. Having done mathematical proofs, data structures and algorithms and currently doing algorithm design, I have spent large amounts of time on websites such as StackOverflow, GeeksForGeeks and LeetCode. Having gone through a structured learning path has given me the ability to quickly "parse" chuckles though these websites. These sites serve their own different purposes and clearly have their own attitudes towards learning. StackOverflow has a lot of rules related to conduct. GeeksForGeeks assumes everyone is a beginner and explains everything in detail. LeetCode assumes a certain level of knowledge before doing any question - the most basic being code runtime analysis. No one accounts for everyone.
When writing technical articles, there are three kinds of people you have to account for: experts in the field who may challenge you in the comments, people having no prior knowledge in the field but still want to learn about it, people who are in between - not complete amateurs or not experts.
How do we go about doing that?
There are few ways to go about this, but your initial assumption should be that no one has the prerequisite knowledge to understand your writing - even though we know there are three kinds of people. You now have a few options on how to get going:
- The lazy option: Post links to required prerequisite resources before your article. If someone gave me links to go through before the thing I actually wanted to read, 9 time out of 10 I wouldn't. Why? Too time consuming.
- The effective option: Explain everything by giving a detailed explanation and extensive comments. Explain things mathematically, textually and diagrammatically. The effort you put in may not translate into many people understanding it
- The efficient option: Succinctly explain the technical landscape - words, notation, symbols, etc - using a glossary so people can get familiar quickly. Write all your papers/articles building on top of that. When you write about something new, add that into the glossary. Now you have a framework where you can write and publish articles and papers easily without worrying about your audience.
Let's take the example of a proof to illustrate the need for a glossary.
Define: Let spanning tree T, a subgraph of graph G, have edges E and vertices V where |V| = n.
Pause: What is a spanning tree, edge, vertex and induction? To a lot of people it may not seem obvious.
Prove: The spanning tree T has n - 1 edges or |E| = n - 1
Induction Proof:
Base Case: n = 1
If |V| = 1, then |E| = n - 1 = 0
Pause: A tree having one isolated vertex is a valid tree and will not have an edge.
Induction Hypothesis: n = k - 1 ≥ 2, k in N
If |V| = k - 1, then |E| = k - 2
Pause: Isn't induction just assuming a premise to find a conclusion without checking if the premise is true or false? How can you just assume a hypothesis then? That leads to another question: what type of problems is induction an ideal solution to? More context is required here.
Prove: n = k
For a tree G, remove an edge e. Now G has become G1 and G2. G1 has k - 1 vertices and G2 has 1 vertex. By the induction hypothesis, G1 has k - 2 edges and G2 has 0 edges. G now has (k - 2) + 1 = k - 1 edges.
Pause: Even though this explanation seems fine to me, I know the last line may initially be a cause for confusion.
In conclusion
There is a better way of going about technical writing. I do not have all the answers but I do know and have seen a lot of bad ones. We can now at least think of constructing better solutions.
Discussion