Technical Writing and Presenting ================================ The material on technical writing and presenting follows Chapter 15 on Technical Writing by Craig Gunn, in the book of Charles R. MacCluer. Heed the following advice: "*You will be judged in industry not on your work but on how well you communicate your work.*'' Working in Pairs ---------------- One job interview question asks the applicants to describe their collaborative work experience. Collaborations can take many forms. One such form is the :index:`programming in pairs` for which two methodologies can be applied: 1. pair programming Two developers, called driver and navigator, share the same computer. The driver codes. The navigator reads and checks the code. The roles switch from time to time. 2. code review Two developers, called coder and reviewer, share their code. The reviewer suggests changes to the code. The coder adjusts the code based on the review. The roles switch from time to time. The main distinction between pair programming and code review is obviously that pair programming requires relatively long sessions and that almost all work is done during those sessions. In code review, the meetings can be short and are mainly intended to coordinate the progress of the work. Both methods are equally good, but of course it is most important that both members are in agreement with the method of collaboration. Commitments to collaborate must be done early, at the same time of committing to a topic of a project. All members in the collaboration are expected to contribute their fair share in the work. The commitments may change from project to project. Therefore, it is not okay to do very little for one project promising more effort in a later project. Topics for the first Project ---------------------------- Each proposed topic can be summarized into a question, with suggested actions to address the question. Some topics involve data retrieval and interpretation, others involve modeling and are more computational. 1. What is the best CDF for the age of death? Locate a public database for mortality, e.g.: the Illinois department of public health, or census data. 1. Represent the data first as a histogram format, such as the number of deaths in every age group. 2. Construct a polynomial or spline approximation for the CDF. 2. Does the Poisson distribution describe arrivals well? Gather data about the arrivals (or checkouts) of a store, or alternatively locate a public database for the traffic of a particular web site. 1. Model the probability density function and the cumulative probability distribution. 2. Assuming the distribution is Poisson, what is the value for the lambda parameter? 3. Design an overbooking strategy in an airline. Suppose each passenger has the same probability :math:`p` of showing up for the :math:`N` seats on a flight. Each empty seat represents a loss of :math:`L` dollars. Let :math:`m` be the number of extra tickets sold. 1. What is the maximum reparation :math:`R` should be offered to compensate passengers who cannot be given a flight? 2. Use the binomial distribution in your numerical study. 4. What is the expected return of the Illinois lottery? The prizes and odds of winning in the IL lottery are: * :math:`\$2` million (1 in 15,890,700), * :math:`\$2,000` (1 in 60,192), * :math:`\$50` (1 in 1,120), * :math:`\$5` (1 in 60), * :math:`\$2` (1 in 7.8). Consider the following questions: 1. What is the justification for these numbers? 2. Assuming one million tickets are sold, how large should the prize be before :math:`\$1` ticket has an expected return of more than :math:`\$1`. 5. Quality loss of servicing requests Long wait times in a store may lead to a loss of customers. Short checkout times may cause a loss caused by idle cashiers. 1. Run computational experiments to determine the mean and standard deviations 1. of the wait time of the customers, and 2. the idle time of the cashiers. 2. Design a quality loss function for this problem. 6. Explore the central limit theorem. Consider the random variable .. math:: X = \frac{X_1 + X_2 + \cdots + X_N}{\sqrt{N}} where :math:`X_k` is the outcome of the *k*-th flip of a fair coin. 1. Show that :math:`E[X] = 0` and :math:`E[X^2] = 1`. 2. Show experimentally that for large :math:`N`, :math:`X` is normally distributed. 7. Make a Poisson random number generator. Numbers following the Poisson distribution with a given average number of events can be generated following an algorithm listed in volume 2 of the Art of Computer Programming by Donald E. Knuth. 1. Write an implementation for this algorithm. 2. For sufficiently large experiments, compute the mean and the standard deviation of the generated sequences of numbers. 3. Compare with the Poisson distribution we used in Lecture 3. 8. The Substitute Teacher Suppose a school has 100 teachers, who teach 100 days and take one sick day. If all sick days are distinct, then one substitute teacher suffices to cover all teaching. 1. Formulate this question using the binomial distribution. The assumption that all sick days are distinct is unrealistic, what is the probability that one substitute will not suffice? 2. Run Monte Carlo simulations to solve this problem. Interpret the results of the runs and compare with the analysis that applied the binomial distribution. 3. Setup a general model for any number :math:`N` of teachers, any number :math:`D` of teaching days, with the probability :math:`p` that one teacher reports sick. Test your model on the specific :math:`N = 100 = D`, :math:`p = 1/100`. Extrapolate for different probabilities :math:`p`. It is important to commit early to a topic in order to have sufficient flexibility in the two weeks before the start of the project presentations. The technical report is due at the end of the presentations. The Formal Technical Report --------------------------- A technical report contains the following elements: * Title and Abstract The title consists of seven to eight well-chosen words. Its goal is to give a clear understanding of the content. The :index:`abstract` or summary should not be written until all other parts of the report are complete. An abstract is short: only one or two paragraphs, between 250 and 300 words, and stated in simple declarative sentences. It *must* stand alone from the report. * Table of Contents and Nomenclature The table of contents lists each section heading along with page numbers. It does not include itself nor the abstract and is followed by a list of illustrations and a list of tables. The nomenclature is an alphabetic list of all symbols uses (first Latin, then Greek) and lists the extensively used acronyms and abbreviations. Acronyms and abbreviations must be spelled out at their first appearance, e.g., fast Fourier transform (FFT). * Introduction and Analysis The introduction encourages to read on as it describes the motivation: why is your work important. The introduction also provides background: what is the context of your work? The introduction typically ends by describing what follows in the sections. The analysis defines the underlying mathematical basis. It contains the derivation of the specific formulas used to handle and interpret the data from well-known basic relationships. Readily available results form the literature are quoted. The purpose of the analysis is that it should be self-contained, the reader should not consult other sources. * Experimental Equipment and Procedure The key algorithms used should be defined clearly. For computational experiments, the specifications of all software and computers should be listed. In this way, experiments can be reproduced by someone familiar with the general area. Every table and picture must have a clear caption, and provide a legend for column headers and coordinate axes. Never include tables or pictures not mentioned in the text. * Results and Discussion The results section presents answers obtained from experiments, referring to tables and pictures, informing about the analysis of the data. Some readers will jump immediately to the results section. The discussion summarizes the results, separating the new from the "as expected.'' It compares with similar investigations, pointing out strong points and the limitations of the work. The interpretation of the results progresses logically, starting what what is known first, and then what is new second. * Conclusions, References, and Appendices The conclusions state concisely the results and the discussion and are a clean synthesis without further explanation. For each reference, list the author(s), title, and publisher. For online references, list the URLs. Appendices may contain the complete listing of a program and the output of calculations. In approaching a writing task, start with the question: Who will read what you are writing? In case of multiple authors, pass the text around and discuss your changes to arrive at a neutral, uniform narrative flow. Keep in mind that technical writing is direct, concise, and clear. Start early and read, revise, read, revise, etc. Concerning the technical aspects of writing, you could start with a well structured and documented Jupyter notebook, which allows for the inclusion of LaTeX, the standard for mathematical typesetting. When writing by hand one is not distracted by layout and has a better ability to focus on ideas and content. The use of a spelling checker is mandatory. Consider applying programs to check the grammar. Project Presentations --------------------- Recommendations on how to present a project well are shown in :numref:`figPPslides`. .. _figPPslides: .. figure:: ./figPPslides.png :align: center Seven slides with recommendations for presentations. Bibliography ------------ 1. Craig Gunn and Charles R. MacCluer, Chapter 15 of *Industrial Mathematics. Modeling in Industry, Science, and Government*, Prentice Hall, 2000. 2. W. Strunk and E.B. White. *The Elements of Style*. Fourth Edition. Longman Publishers, 2000.