Non-Technical Guide to Writing a Report

# Non-Technical Guide to Writing a Report *by Vitaly Romanov* ## What is a Report? A report is a tool for conveying information. A report can be done in many different forms, including text, speech, audio, video, etc. According to one of the definitions, [report means](http://www.businessdictionary.com/definition/report.html) > A document containing information organized in a narrative, graphic, or tabular form, prepared on ad hoc, periodic, recurring, regular, or as required basis. Reports may refer to specific periods, events, occurrences, or subjects, and may be communicated or presented in oral or written form. The most important point to grab from here is that the report aims to deliver the information and can be done in many different forms. ## Before Writing a Report Before you start, it is essential to identify your goal and your audience (yes, like they say in any guide on how to present). In university setting, the goal most likely will be to inform about what you have done, and what your results are. The audience is usually your peers, your professor or your TA. The safest assumptions to make is that the person who will consume your report has a background similar to yours, but is unaware of what you were trying to achieve. Before you start writing, it is reasonable to think about the structure of your report. A clear structure is the key to success. The most common outline has the following form 1. Motivation; here you specify what you are trying to do and why. 2. Background; might be necessary if you do a research report 3. The body of the report, this part is topic specific. Usually, you divide the whole body into logical parts, i.e. steps necessary to completing (understanding) your work 4. Conclusion; this part should correspond with your motivation. 5. Appendix; where you place information helpful, but not essential for understanding. 6. References; always document where the information you present comes from. References are good for you: make it easy to remember where the information came from, have access to a more lengthy description of what you present, make it easier to restore memory when you come back to the project after three months. References are good for the reader: the reader can evaluate the validity of your information and can go on researching the subject ## Writing a Report One of the important points to understand is that one way of presenting the information can be effective in one case, but is highly unwelcomed in other scenarios. Take text for example. It is good for presenting a complex idea, to describe a relationship between different objects. However, text takes time to read and search. It is an unstructured way of presenting information. Concepts are easier to present with alternative forms. ### Figures Figures are probably the second most popular way of presenting the information. For academic reports they usually imply graphs. Graphs can convey more information in a second visually than you can do with 100 words. What should you consider when preparing a figure? - Size Too small figures are bad, too large figures are bad as well. If your figure has very few details, there is no need to make it half-page size. If the information can be understood from a smaller figure, it is rather preferred. Otherwise, you create an information vacuum on your page. Figures that have fine details or text should be scaled accordingly. The reader should be able to read the content easily. - Axes Always annotate your axes. The reader may not be aware of what you meant. Additionally, when you annotate, the chance of making silly mistakes, like using a wrong figure, is smaller. - Legend A legend is a simple way to make your figure more descriptive - Make use of line styles If you have several lines, use different colors, marker, line styles, line thickness - Title or description A figure should be self-sufficient. Make it describe your point Example of bad figure is <img src=https://www.dropbox.com/s/jnzzxh4qzwq13j9/bad-figure.png?dl=1 width=700/> Example of a good figure is <img src=https://www.dropbox.com/s/g24o72atl3cbezo/good-figure.png?dl=1 width=500/> ### Tables A table is an excellent way of presenting information that is abundant and structured. What takes a paragraph of boring reading, can be summarized into a [table](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#tables) | Stock | Ticker | P/E | Market cap | Share price | | -------------| -----|----: |-------------:| -----:| | Yandex | YNDX | 39 | 9.635B | 29.70$ | | Amazon | AMZN | 103 | 814.392B | 1,665.53$ | | Alibaba | BABA | 48 | 382.580B | 147.59$ | What you should keep in mind about tables - They help when you have structured information - They are concise, yet clear - Avoid writing a lot of text in cells - Try to fit a table into a field of view ### Code There is an eternal debate whether you should comment your code, or simply give readable names to methods and variables. In some cases, a piece of code in the middle of the report can be helpful. Most of the time, unfortunately, long methods that are hard to read and comprehend hinder the understanding. Code listings are a great example of information noise and their place is in the appendix. ``` def merge_sort(L): mid = int( (len(L) - 1)/2 ) if len(L) > 2: a = merge_sort(L[0:mid]) b = merge_sort(L[mid:len(L)]) elif len(L) == 2: a = [L[0]] b = [L[1]] else: return L i = 0 j = 0 new = [] while (i!= len(a) or j != len(b)): if i < len(a) and j < len(b): if a[i] < b[j]: new += [a[i]] i += 1 else: new +=[b[j]] j += 1 elif i == len(a) and j != len(b): new += [b[j]] j += 1 elif j == len(b) and i != len(a): new += [a[i]] i += 1 else: break return new ``` It is hard to follow what the code above is doing from a brief glance, isn't it? That is, if you do not already know what it does. But if you do, no need for the code anyway. If you want to describe your algorithm, use pseudocode like this <img src=https://www.dropbox.com/s/3k24hszzwct7hdf/pseudocode.png?dl=1> Example above is more concise and more human-friendly. This is the case for a low level algorithm. If you describe a small and more high-level algorithm that is easy to read, using the code is really normal ```python def cache_images(batch_pahts, cache): for image_path in batch_paths: if image_path not in cache: img = load_image(image_path) cache[image_path] = CNN(img) ``` ### Information Noise Sometimes you read a report, and in a paragraph, there is a sentence of valuable information. The rest is noise. Information noise should be avoided at all costs. There is no purpose in pursuing thicker reports and higher page count numbers. Be concise and right to the point. This is an informal recipe for a successful report. ### Common Mistakes - Lack of structure - Start your report with code - Incorrect usage of figures - Overuse of textual presentation - Information noise - Missing information - Incoherent narration - Appendix underuse - No references when referring to others' people work ## Concluding Remark Writing report, like any writing, can be considered a form of art. The best way to become proficient is to write more of them. In your reports, place more emphasis on what you did, why and how you did it. Present your results in a convenient way, so that it is easier for the reader to comprehend. Be concise and straight to the point. Use references to guide the reader in case background information is needed. ## Further Reading 1. [Most Popular Web-Site](https://www.google.ru/search?q=how+to+write+academic+report&newwindow=1&ei=h5jZW8noC8ydsgH13ojABA&start=10&sa=N&ved=0ahUKEwiJyJP9z7DeAhXMjiwKHXUvAkgQ8tMDCJoB&biw=1853&bih=981) 2. [Guide to Figures](https://writingcenter.unc.edu/figures-and-charts/) 3. [Guide to Figures and Tables](http://abacus.bates.edu/~ganderso/biology/resources/writing/HTWtablefigs.html) 4. [LaTeX for Pseudocode](https://reachmnadeem.wordpress.com/2015/03/04/pseudocodealgorithm-editor/) 5. [Figure Formatting with PyPlot](https://matplotlib.org/users/pyplot_tutorial.html)