summaryrefslogtreecommitdiff
path: root/book/module2/documentation.tex
diff options
context:
space:
mode:
Diffstat (limited to 'book/module2/documentation.tex')
-rw-r--r--book/module2/documentation.tex64
1 files changed, 0 insertions, 64 deletions
diff --git a/book/module2/documentation.tex b/book/module2/documentation.tex
deleted file mode 100644
index ebd9d87..0000000
--- a/book/module2/documentation.tex
+++ /dev/null
@@ -1,64 +0,0 @@
-\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}