fix(sw dev1): typos in notes

workshops/software_development/sections/documentation.tex

@@ -21,19 +21,20 @@
         \item \alert{Code comments}, \lst{Readme} file, User/developer manual, Wiki, ...
       \end{itemize}
   \end{itemize}
-  \note[item]{See \textit{handbook-first} approach for interesting blog posts,
+  \note[item]{See \textit{handbook-first} approach for interesting blog posts
   and more details.}
   \note[item]{Making the documentation transparent \textit{before} dissemination
-  of the code allow it to be treated as a \textit{single source of thrust}. All
-  contributors will look into the documentation to understand why and what the
-  software does. No need to look into various chat apps or mails or what we
-  believe is true.}
+  of the code allows it to be treated as a \textit{single source of thrust}. All
+  contributors will look into the documentation to understand what the
+  software does and the reasons it was implemented that way.
+  No need to look into various chat apps, mails or to rely on our partial
+  understanding.}
   \note[item]{An excellent documentation increases tremendously the efficiency
   on collaborative projects. It completely removes back-and-forth communication
-  and interpretations based on misunderstandings.}
+  and misinterpretations based on poor code understanding.}
   \note[item]{The more a project grows, the more \textbf{vital} the
-  documentation becomes. In the same time, beginning the documentation of an
-already established project is an massive and complicated task.}
+  documentation becomes. At the same time, beginning the documentation of an
+  already established project is a massive and complicated task.}
 \end{frame}
 
 \begin{frame}{\insertsectionhead}
@@ -69,22 +70,28 @@ already established project is an massive and complicated task.}
       \end{itemize}
     \pause
     \item Use general comment blocks as function header
-      \begin{itemize}
-        \item In \matlab, used for \lstmat{help} and \lstmat{lookfor}
-
-          \begin{lstlisting}[
-    language=matlab,
-    frame=single,
-  ]
+      \begin{lstlisting}[
+      language=matlab,
+      frame=single,
+      ]
 function z = sum(x,y)
   % SUM  Returns the sum of the two inputs
   %   Usage:
   %     z = SUM(x,y), returns z, the sum of x and y,
   %     where both x and y are scalars.
 
-          \end{lstlisting}
-      \end{itemize}
+      \end{lstlisting}
   \end{itemize}
+  \note[item]{In \matlab, the first line of comment is used for the
+  \lstmat{lookfor} function. This allows you to find functions based on
+  keywords. It is a really powerful way to find the correct function if you
+  know what it does.}
+  \note[item]{In \matlab, the first \textit{continuous} block of comment is
+  printed when using the \lstmat{help} command. You can get inspiration by
+  looking at matlab built-in codes with \lstmat{edit <functionName>}.}
+  \note[item]{If the code is public, it is a good practice to put a copyright
+  notice in the header of all files (no need to reproduce it in length, just the
+  name of the license is sufficient.}
 \end{frame}
 
 \begin{frame}[fragile]{\insertsectionhead}
@@ -202,7 +209,7 @@ z = x + y % add y to x and put it in z
   \end{itemize}
   }
   \note[item]{Some languages have specific file types that can include the
-  documentation alongside the code. This is the case for Latex and the \lst{dtx}
+  documentation alongside the code. This is the case for Latex and the \lst{dux}
   files. With that, the documentation is included in the code directly and files
   are parsed with the latex interpreter to separate the documentation pdf and
   the latex package code.