doc: update text for lecture 7 about documentation

lectures/revealjs/07-lecture-documentation.adoc

+= Documentation 
+:customcss: slides.css
+:icons: font
+:includedir: includes/
+:LECTURE_TOPIC: Documentation
+:LECTURE_NO: 7th lecture
+
+include::{includedir}header.adoc[]
+
+[.smaller-80][.center-paragraph]
+IT1901 Fall 2022 - {LECTURE_NO}
+
+
+[background-color = "#124990"]
+[color = "#fff6d5"]
+== Overview
+[.smaller-80]
+- Documentation
+- Markdown
+- Gitlab Flavoured Markdown (GFM)
+- PlantUML
+- Commit messages
+
+
+[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)
+
+[source,java, role="stretch"]
+----
+/**
+  * Creates a LatLong object from a String, using a specific separator.
+  * The format is <latitude><separator><longitude>.
+  * @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. 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
+
+== Plant UML
+
+- open source tool for UML diagrams
+- it takes a textual description and produces a diagram
+- supported within markdown in GitLab
+- uses Graphviz to lay out the diagrams
+
+== Adding diagrams to markdown 
+
+[source, role="stretch"]
+----
+```plantuml
+class LatLong {
+	double latitude
+	double longitude
+}
+class LatLongs
+LatLongs *--> "*" LatLong: "latLongs"
+class MetaData
+LatLong *--> "1" MetaData: "metaData"
+```
+----
+
+
+[background-color = "#124990"]
+[color = "#fff6d5"]
+== Commit messages
+
+== Commit messages
+
+- Commit messages allow the developers to attach a description to the commits. 
+- overview of the project history
+- the better the commits messages the easiest is to navigate the project history and understand what happened
+
+== Commit message anatomy
+
+- Subject / Title    -  Essence of the commit in a few words     
+- Body - Extended textual description of what has been done 
+- Footer - Additional elements such as links to issues and other metadata 
+
+== Basic principles
+
+- be consistent
+- limit the subject line to 50 characters
+- don't put a period at the end of the subject line
+- put a blank line between the subject line and the body text
+- wrap the body text at 72 characters
+- use the imperative mood 
+- describe *what* and *why*, but not *how*
+- mention which component(s) / area changed.
+
+
+include::{includedir}footer.adoc[]
\ No newline at end of file