From 93a0862774cf9c411b9d3148b378454604142f6f Mon Sep 17 00:00:00 2001
From: Adrian Stoica <stoica@ntnu.no>
Date: Wed, 25 Sep 2024 12:45:08 +0200
Subject: [PATCH] docs: add slides for the 5th lecture

---
 lectures/revealjs/06-documentation.adoc | 442 ++++++++++++++++++++++++
 1 file changed, 442 insertions(+)
 create mode 100644 lectures/revealjs/06-documentation.adoc

diff --git a/lectures/revealjs/06-documentation.adoc b/lectures/revealjs/06-documentation.adoc
new file mode 100644
index 0000000..1c5dda4
--- /dev/null
+++ b/lectures/revealjs/06-documentation.adoc
@@ -0,0 +1,442 @@
+= Documentation
+:customcss: slides.css
+:icons: font
+:includedir: includes/
+:LECTURE_TOPIC: Documentation
+:LECTURE_NO: 6th lecture
+
+include::{includedir}header.adoc[]
+
+
+[.smaller-80][.center-paragraph]
+IT1901 Fall 2024 - {LECTURE_NO}
+
+== Overview
+
+- Administrative issues
+- Documentation
+- Summary
+
+
+[background-color = "#124990"]
+[color = "#fff6d5"]
+== Administrative issues
+
+== 1st individual exercise
+
+- 2 thirds got it approved
+- last chance to deliver
+- mandatory exercise 
+- new deadline 03.10.2024 23:59
+
+
+
+== Approaching Deadlines
+
+- Torsdag, 03. oktober / 23:59 
+** 1st individual exercise
+
+- Torsdag, 10. oktober / 23:59 
+** 2nd group deliverable
+
+
+[background-color = "#124990"]
+[color = "#fff6d5"]
+== Documentation
+
+== Documentation
+
+- is an important part of software development
+- a way to ensure and contribute to 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
+
+[.smaller-80]
+- design documentation
+- API specifications ( if applicable)
+- readme files
+- contribution guide
+- frequently asked questions (faq)
+- wiki
+- comments ( including Javadoc ) 
+- user guides
+- ...
+
+
+== 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 (1)
+
+- give overview information regarding a project, subproject, module
+- normally contains info about the role, contents, build details, dependencies and interactions with other parts / modules
+
+== Readme files (2)
+
+- can contain information such as setting up environment, installing dependencies and other needed software, building, running the project
+- 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 &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);
+}
+----
+
+== Comments (4)
+
+- comments should bring additional value
+- most source file formats support some type of comments
+- for example: project needs a certain version of a dependency 
+** we can document that in the readme or some specific file dealing with building and running
+** we can also add a comment exactly where one would go and change the config file 
+
+== Documenting unit tests
+
+- use javadoc
+- use @DisplayName annotation
+- use @Tag annotation
+
+== Over-documenting
+
+- documentation needs to be concise
+- redundant documentation will result in maintenance overhead
+- if some entity / operation is clear and self evident, 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)
+
+
+== Documentation file formats
+
+- text based file formats
+- can be tracked using source code management tools
+- do not depend on a specific editing sofware
+
+[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
+
+
+[background-color = "#124990"]
+[color = "#fff6d5"]
+== UML Diagrams
+
+[.smaller-80]
+== UML - Unified Modelling Language
+
+- 13 diagrams that show various perspectives on the system
+
+- purpose:
+** Stimulate and focus discussion about an existing or a new system
+** Document an existing system
+** Detailed description to generate a system
+
+- informal use of UML:
+** “I do not find UML to be useful during the design process itself and prefer informal notations that are quicker to write and that can be easily drawn on a whiteboard.” (Sommerville, s. 175)
+
+== !
+
+image::../images/lecture13/uml-diagrams.png[canvas, size=contain]
+
+[.smaller-20]
+[.left-30] 
+Fowler, Martin., (2003). UML distilled: a brief guide to the standard object modeling language. Pearson Education
+
+[background-color = "#124990"]
+[color = "#fff6d5"]
+== Package diagram
+
+[.smaller-80]
+== Package diagram
+
+- Gir en oversikt over avhengigheter mellom moduler av et system
+- Viser “pakker” - typisk grupper av klasser
+- Viser avhengigheter mellom pakker/moduler
+- Hver klasse er kun medlem av en “pakke”
+- Pakker representerer et hierarkisk navnerom, så hver klasse innen en pakke må ha et unikt navn
+- En pakke skal ikke kunne være medlem av flere moduler
+
+[.smaller-30]
+Fowler, Martin., (2003). UML distilled: a brief guide to the standard object modeling language. Pearson Education.
+
+
+== !
+
+image::../images/lecture13/package-diagram.png[canvas, size=contain]
+
+[background-color = "#124990"]
+[color = "#fff6d5"]
+== Class diagram
+
+
+== Class diagram
+
+- Viser typer objekter i systemet og statiske relasjoner mellom dem
+- Enkleste form: Klassenavn i bokser
+- Viser egenskaper (attributter, assosiasjoner) og operasjoner (metoder) for en klasse
+
+
+[.smaller-30]
+Sommerville: Software Engineering, Pearson, 2016. 10th Edition, page 149.
+
+== !
+
+image::../images/lecture13/class-diagram-1.png[canvas, size=contain]
+
+[.smaller-30]
+[.left-30]
+Kilde: Yngve Lindsjørn, Universitetet i Oslo: IN2000: Kravhåndtering, modellering & design.
+
+
+== !
+
+image::../images/lecture13/class-diagram-2.png[canvas, size=contain]
+
+
+[.smaller-30]
+[.left-30]
+Kilde: Yngve Lindsjørn, Universitetet i Oslo: IN2000: Kravhåndtering, modellering & design.
+
+
+[background-color = "#124990"]
+[color = "#fff6d5"]
+== Sequence diagram
+
+[.smaller-80]
+== Sequence diagram
+
+- Brukes for å analysere samarbeid mellom objekter
+- Modellerer interaksjoner mellom aktører og objekter i et system og interaksjon mellom objekter i et scenarie
+- Aktører og objekter finnes øverst i diagrammet
+- Tidsakse nedover i diagram
+- Piler indikerer interaksjon mellom objekter
+- Annoterte piler indikerer metodekall
+- Kan vise alternative sekvenser
+
+[.smaller-30]
+Sommerville: Software Engineering, Pearson, 2016. 10th Edition, page 146.
+
+== !
+
+image::../images/lecture13/sequence.png[canvas, size=contain]
+
+== !
+
+```puml
+
+actor User
+User -> "~#newTodoItemButton: Button" as newTodoItemButton: click
+newTodoItemButton -> TodoController: handleNewTodoItemAction
+TodoController -> "~#newTodoItemText: TextField" as newTodoItemText: getText
+TodoController -> TodoList: addTodoItem
+TodoList -> TodoList: fireTodoListChanged
+TodoList -> TodoListListener: todoListChanged
+TodoListListener -> TodoController: autoSaveTodoList
+TodoListListener -> TodoController: updateTodoListView
+
+```
+
+
+
+
+
+== 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
+
+[.smaller-80]
+- 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.
+
+
+
+== Commit messages (2)
+
+image::../images/git_commit_2x.png[size=75%]
+[.smaller-40]
+https://xkcd.com/1296/
+
+
+
+
+== Conventional commits format
+
+```text
+<type>([optional scope]): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+== More on conventional commit content (1)
+ 
+- fix: a commit of the type fix patches a bug in your codebase 
+- feat: a commit of the type feat introduces a new feature to the codebase 
+- BREAKING CHANGE: a commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change. A BREAKING CHANGE can be part of commits of any type.
+
+== More on conventional commit content (2)
+
+- more types:  build, chore, ci, docs, style, refactor, perf, test
+- footers other than BREAKING CHANGE: `<description>` may be provided and follow a convention similar to git trailer format (`token: value`).
+
+== Why to use the conventional commits?
+
+[.smaller-80]
+- Automatically generating CHANGELOGs.
+- Automatically determining a semantic version bump (based on the types of commits landed).
+- Communicating the nature of changes to teammates, the public, and other stakeholders.
+- Triggering build and publish processes.
+- Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history.
+
+
+== What to write in the commit message
+
+[.smaller-80]
+- the subject line is the most important
+- clearly state the original issue / problem
+- clearly state *why* the change is made
+- minimize external reference use and aim at a self contained message
+- clearly state how the problem is fixed with the committed code 
+- add information about testing, especially if there are manual tests needed  
+
+Finally, read the message before committing as it might reveal that you should split it in smaller commits
+
+
+
+[background-color = "#124990"]
+[color = "#fff6d5"]
+== Questions ?
+
+
+[background-color = "#124990"]
+[color = "#fff6d5"]
+== Summary
+
+
+
+include::{includedir}footer.adoc[]
-- 
GitLab