From 8ab48120f03185a051f652b18f97439265884221 Mon Sep 17 00:00:00 2001
From: Christian Kolset <christian.kolset@gmail.com>
Date: Tue, 29 Apr 2025 18:34:26 -0600
Subject: Added tex files to book/

---
 book/module2/documentation.tex | 64 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 book/module2/documentation.tex

(limited to 'book/module2/documentation.tex')

diff --git a/book/module2/documentation.tex b/book/module2/documentation.tex
new file mode 100644
index 0000000..ebd9d87
--- /dev/null
+++ b/book/module2/documentation.tex
@@ -0,0 +1,64 @@
+\section{Documentation of your code}\label{documentation-of-your-code}
+
+Code documentation is essential for maintaining and scaling software
+projects. Whether it's an open-source project or your own private code.
+It ensures that you can understand, use, troubleshoot and build upon the
+code in the future.
+
+\subsection{Keep Detailed and Accurate
+Notes}\label{keep-detailed-and-accurate-notes}
+
+Just as a recipe requires clear instructions, your code should be
+accompanied by comprehensive notes. Document your process thoroughly to
+ensure that others (and future you) can follow along without confusion.
+
+When documenting a project, it's essential to include detailed notes
+that capture not just what the code does, but how it was developed. This
+includes recording libraries used, citing any external code snippets
+along with their sources, and outlining the sequence of steps taken
+throughout the coding process. Such comprehensive documentation enables
+others---and your future self---to understand, recreate, and maintain
+the project more effectively, reducing confusion and improving long-term
+usability.
+
+\subsection{Explain Your Decisions}\label{explain-your-decisions}
+
+In programming, there are often several valid approaches to solving a
+problem. When documenting your code, it's important to clarify why you
+chose a particular method---especially if it deviates from common
+practices. Anticipating potential questions and addressing them directly
+in your documentation helps others follow your reasoning and builds
+trust in your solution. \includegraphics{figures/rubberDuck.png} A
+useful strategy for articulating these decisions is the ``rubber duck''
+technique---explaining your code as if you're teaching it to someone
+else. Whether spoken aloud or written down, this practice helps you
+clarify your logic and communicate the reasoning behind your choices,
+providing valuable context for future collaborators or
+reviewers.\hspace{0pt}
+
+\subsection{Include a README}\label{include-a-readme}
+
+A README file serves as the introduction to your project. It should be
+placed in the top-level directory and provide essential
+information.\hspace{0pt} A good readme file may include: - Project title
+and description - Installation instructions - Usage examples -
+Contribution guidelines (if applicable) - License information (if
+applicable)
+
+This file acts as a roadmap for anyone interacting with your project.
+\hspace{0pt}
+
+\subsection{In-line Comments}\label{in-line-comments}
+
+While external documentation is vital, in-code comments provide
+immediate context. Use them to explain complex logic or important
+sections within your code.\hspace{0pt}Here are some guidelines to
+follow: Keep comments concise and relevant. Avoid stating the obvious;
+focus on the ``why'' rather than the ``what.''.
+
+\subsection{Maintain and Update
+Documentation}\label{maintain-and-update-documentation}
+
+Similarly to your code, the documentation should evolve alongside your
+code. Regularly review and update it to reflect changes, ensuring
+accuracy and relevance.\hspace{0pt}
-- 
cgit v1.2.3

