Merge branch 'master' of https://gitlab.stud.idi.ntnu.no/it1901/course-material.git

lectures/revealjs/07-documentation.adoc

+= Documentation 
+:customcss: slides.css
+:icons: font
+
+++++
+	<img id="main-logo" class="main-logo" src="images/template/main_logo_eng_no_text.png" width="300" alt="ntnu logo"/>
+++++
+
+[.smaller-80][.center-paragraph]
+IT1901 Fall 2019 - 7th Lecture
+
+
+[background-color = "#124990"]
+[color = "#fff6d5"]
+== Overview
+[.smaller-80]
+- Documentation
+- Markdown
+- Gitlab Flavoured Markdown (GFM)
+
+
+[background-color = "#124990"]
+[color = "#fff6d5"]
+== Documentation
+
+== Documentation
+
+- is an important part of software development
+- a way to ensure software quality
+- several levels of documentation
+
+[.smaller-60]
+Note: In IT1901 we also look if the documentation is original. You should not just copy paste the documentation from the examples and just rename things to match your project.  
+
+== Types of documentation
+
+- Design documentation
+- API specifications ( if applicable)
+- readme files
+- contribution guide
+- frequently asked questions (faq)
+- wiki
+- comments ( including Javadoc ) 
+
+== Who is reading the documentation
+
+- the developer him/herself
+- other developers 
+- future maintainers of the software product
+- external users (e.g. some provided API)
+- others within the company / institution (testers, deployment )
+- ....
+
+== How is documentation improving the quality
+
+- allow new team members to be productive faster
+- increase qualities such as maintainability and transferability
+- saves time for both other contributors and initial dev
+
+== Readme files
+
+- give overview information regarding a project, subproject, module
+- normally contains info about the role, contents, build details, dependencies and interactions with other parts / modules
+- it is a way to provide needed contextual information that otherwise is not apparent from just looking at the source code 
+
+== Comments (1)
+
+- allow adding documentation in close proximity with the code
+- they should not be a way to cope with bad naming or "special" assumptions in the code
+- the standardized comments such as JavaDoc allow  additional benefits such as code completion
+
+== Comments (2)
+
+[.center-paragraph]
+image::../images/lecture07/code-comments.png[width=100%]
+
+[.smaller-40]
+https://stfalcon.com/uploads/images/55c8bcff18b94.png
+
+== Comments (3)
+
+``` java
+   /**
+     * Creates a LatLong object from a String, using a specific separator.
+     * The format is &lt;latitude&gt;&lt;separator&gt;&lt;longitude&gt;.
+     * @param s the String to parse
+     * @param sep the separator
+     * @return the new LatLong object
+     */
+    public static LatLong valueOf(final String s, final String sep) {
+      final int pos = s.indexOf(sep);
+      if (pos < 0) {
+        throw new IllegalArgumentException("No '" + sep + "' in " + s);
+      }
+      final double lat = Double.valueOf(s.substring(0, pos).trim());
+      final double lon = Double.valueOf(s.substring(pos + sep.length()).trim());
+    
+      return new LatLong(lat, lon);
+    }
+``` 
+
+== Over-documenting
+
+- documentation needs to be concise
+- redundant documentation will result in maintenance overhead
+- if some entity / operation is clear and self then it does not normally need additional documentation
+
+== ! 
+
+[.center-paragraph]
+image::../images/lecture07/comment-all.jpeg[width=400]
+
+[.smaller-40]
+[.center-paragraph]
+https://miro.medium.com/max/1138/1*Pyxsc7Uixbitv5myywaA_Q.jpeg (Gary Larson comic)
+
+[background-color = "#124990"]
+[color = "#fff6d5"]
+== Markdown
+
+== Markdown 
+
+[.center-paragraph]
+Markdown is a lightweight markup language with plain text formatting syntax. Its design allows it to be converted to many output formats, but the original tool by the same name only supports HTML.[8] Markdown is often used to format readme files, for writing messages in online discussion forums, and to create rich text using a plain text editor.
+
+[.smaller-40]
+https://en.wikipedia.org/wiki/Markdown
+
+== Markdown Syntax
+
+https://www.markdownguide.org/basic-syntax
+
+
+[background-color = "#124990"]
+[color = "#fff6d5"]
+== Gitlab Flavoured Markdown (GFM)
+
+== Gitlab Flavoured Markdown (GFM) 
+
+https://gitlab.stud.idi.ntnu.no/help/user/markdown
+
+== Why text based documentation
+
+- it is easier to modify and we do not need any special editors
+- it can be versioned same way as the code
+- holding  documentation in the repository and updating it will allow consulting the repository contents with the correct documentation for that snapshot in time
+
+++++
+ <div id="footer" class="footer">
+ 	<div style="display:table-row;">
+     <span class="element" style="width:150px;">
+     	<a href="https://www.ntnu.no" target="_blank">
+     		<img 	id="footer-logo" class="footer-logo" 
+     				src="images/template/logo_ntnu.png" 
+     				alt="ntnu logo" height="28"/>
+     	</a>
+     </span>
+     <span class="element" style="width:300px;">| IT1901 - 7th lecture </span>
+     <span class="element">| Documentation </span>
+     <span class="element">&nbsp;&nbsp;&nbsp;&nbsp;</span>
+  </div>   
+ </div>
+ 
+ <div id="vertical-ntnu-name" class="vertical-ntnu-name">
+ 	<span class="helper"></span>
+ 	<img src="images/template/vertical-ntnu-name.png" alt="Norwegian University of Science and Technology" />
+ </div>
+ 
+ <script type="text/javascript">
+     window.addEventListener("load", function() {
+         revealDiv = document.querySelector("body div.reveal")
+         footer = document.getElementById("footer");
+         revealDiv.appendChild(footer);
+         
+         titleSlideDiv = document.querySelector("div.slides section.title")
+         mainLogo = document.getElementById("main-logo");
+         titleSlideDiv.prepend(mainLogo);
+         
+         vertName =  document.getElementById("vertical-ntnu-name");
+         revealDiv.appendChild(vertName);
+     } );
+ </script>
+++++
\ No newline at end of file