By: Glen Berseth

One way to think of paper writing and organization is like writing software. We can’t just dive right into writing the code for the software; we need to use prior libraries, use good syntax and organization to make the code compilable in the reader's mind, and make the ideas and purpose of the code clear. To help accelerate writing paper outlines/skeletons, let's think of them as if we were writing software or a math proof.

Consider the following outline, where the inclusion or organization of text is motivated by if a similar structure would be considered when writing software.

1. Why is this new software needed (Introduction)?
   1. A description of why we need to write this code, why other code does not do the job we want, and what the advantages of this code over prior code.
   2. This should be the preamble or logic in your mind that explains why we should spend time creating this “code” and how it will be useful to others and our future selves.
   3. Now the reader should understand if the code you are going to produce will be relevant to what they need for their code.
2. More details on what other libraries/works exist and why they are not good enough
   1. Just like when we search for what software libraries are available to understand how much code we need to make vs what is already available, we can apply this thought process to writing and what prior works explain but miss that we want to add.
      1. A similar concept is true if you want to think more math framework-focused. We need to explain what axioms/lemmas/theorems already exist and why they are not good enough to explain/solve the desired problem.
   2. Also, in our code, we do not import every library we have ever used. For better code, we are selective, only importing and understanding what is necessary for the code to work and produce the desired result(s).
      1. Trim the related work and group together similar libraries/prior works.
   3. Now the reader can understand what libraries you have “imported” to your code.
      1. There may be a main function, but it does not do much yet.
3. Boiler-plate code or base framework (background section).
   1. What prior code is being extended? One way to build on code is to take a prior library and add the new algorithm to that library. If this is the template, then first we need to explain how the code for the prior methods works. If we don’t do this well, the reader will not be able to “compile” the next section in their head. One can not envision how to train a deep network without having the concept of a tensor operation library (Torch, Tensorflow, Jax, etc)
   2. Now the reader can understand how the prior code works. They can “compile” and run that code, and their mind now understands what to expect for the output.
4. Now, explain our new changes to the code (method section)
   1. Now we can finally add our new/novel code. First, explain what the code/method should do! Then the reader can follow along and respond quickly if someone reads a line they think won't fit into the plan for how they would perform the code.
   2. We must write about our new method in detail. Another person must be able to understand how to take that text (code) and compile the program in their mind, and not have compile-time or run-time errors. The reader may not understand the outcome of the code yet, but it must compile
      1. Writing <-> software
      2. The notation must be correct <-> the datatypes and syntax must be correct
      3. Diagrams are used to provide understanding <-> Documentation in code provides a template
      4. Paragraphs define overall operations <-> function definitions provide inputs and outputs
   3. Order matters. Can’t use variables before they are clearly defined.
      1. No (this will not compile)
         1. Z = X + Y
         2. X = 14
      2. Yes
         1. X = 14, Y = 23
         2. Z = X + Y
   4. An algorithm, like writing, has control of flow.
      1. Avoid breaks in the control of flow, where readers need to flip back or forward pages to find definitions.
      2. Paragraphs and sentences should connect to each other, and the output of one paragraph should feed into the input for the next paragraph.
         1. Again, the “code” will not compile if the end of one paragraph/function does not match the input type for the paragraph after.
   5. The reader should be able to mentally compile this new “code.”
      1. None of the above “compiler” rules should be broken.
      2. No ambiguous text should exist.
      3. The section should only talk about the next method, not other code.
   6. Consistent variable naming (use the same terms consistently)
      1. Use the same term/variable identifier for an item throughout the paper.
      2. When coding, if we use X to store a value that will be used later in the code, we can not introduce another name for that variable Y, which we think means the same thing.
         1. Either the code/text will not compile, because Y was never defined,
         2. Or Y was defined and given a similar value, but it is likely that bugs will occur because only one of X or Y will contain the most up-to-date value, but it will not be clear which one is the most recent.
5. How will we test the code/show it works as intended (QA/testing) (Results section)
   1. Now that there is text that can “compile” in the mind of the reader, we need to add some code to validate our new code.
   2. Need to describe what testing library will be used to test the code and why.
      1. The datatypes should be correct
      2. The testing purpose should be similar
      3. What metric will be used to evaluate that code? Assert == True
   3. Ask a QA specialist to help construct the test cases
      1. Ask a collaborator to review the experimental plan. Does the plan encapsulate evaluating the main message and not leave out any obvious corner cases that will result in the method seemingly working, but it was only because important test cases are missing?
   4. Explain prior test cases
      1. If using prior environments, explain them and why they are relevant to evaluate the code/text.
   5. Add context to the results.
      1. Not all testcases are assert x == y, many are more delicate np.allclose(x,y,threshold=0.0001). Why use allclose? If that returns true, explain why allclose with the given threshold is sufficient. This is similar to arguing whether enough random seeds are used or whether the statistical confidence in the results.
   6. How do these results/testcases support the point of writing this code from he first section?
      1. Check the claims. Complete the loop/argument.
      2. We said the code would do a new thing X or thing X faster/better. Is this true? How true?
   7. Now, the reader can compile the code and the testing code in their methods and envision the outputs for that code/text.
6. Summary of code/work (Conclusion)
   1. Thoughts on the code/text to review its creation
   2. Thoughts on how this code can be used for other problems (future work)