Differences

This shows you the differences between two versions of the page.

--- tipsandtricks:regardingdocumentation [2021/11/22 09:03] – patrik
+++ tipsandtricks:regardingdocumentation [2023/09/29 07:01] (current) – external edit 127.0.0.1
@@ Line 16: / Line 16: @@
   * [[regardingdocumentation#Chapter 3 - For whom is the documentation?|Chapter 3 - For whom is the documentation?]]
     * [[regardingdocumentation#For collaboration|For collaboration]]
+    * [[regardingdocumentation#Choosing a tool|Choosing a tool]]
+    * [[regardingdocumentation#Update or not|Update or not]]
+  * [[regardingdocumentation#Chapter 4 – Contributors|Chapter 4 – Contributors]]
+    * [[regardingdocumentation#Voluntary contributors|Voluntary contributors]]
+    * [[regardingdocumentation#Non voluntary contributors|Non voluntary contributors]]
+    * [[regardingdocumentation#Education|Education]]
 ==== Abstract ====
+Documentations is a loose concept. This document is a try to clarify about what documentation is and how to use it from a technologically point of view. Most of the information is pointed towards documentation in the information technology (IT) sector. \\
-Documentation is a loose concept. This document is a try to clarify about what documentation is and how to use it from a technologically point of view. Some (but not all) things to answer:
+\\
+Some (but not all) things to answer: \\
   * Different kind of documentation.
@@ Line 41: / Line 48: @@
 === Descriptive documentation ===
-Descriptive documentation is usually an overview over something. A more top view on how things are working. Little or no technical information is included.  Examples:
+Descriptive documentation is usually an overview over something. A more top view on how things are working. Little or no technical information is included.  \\
+Examples:
   * A network schematics over a network or setup with several servers.
@@ Line 69: / Line 77: @@
 ==== Chapter 3 - For whom is the documentation? ====
+Is it just for the little team or single person or for a bigger group? Mabey the whole company? \\
-Is it just for the little team or single person or for a bigger group? Mabey the whole company? \\  Will there be one author or is it a collaboration between several parties involved in the documentation? \\
+\\
+On what complexity/technical level should the documentation be written? \\
-A thing to keep in mind is to start with how! \\  How do you want the documentation and then try to find a tool to work with the how. Not the other way around, I.e., implement a tool and then try to make it work.\\
+\\
+How sensitive is the information in the documentation, if it was to ‘leak’ outside of the company? \\
+\\
+Will there be one author or is it a collaboration between several parties involved in the documentation? \\
+\\
 === For collaboration ===
 What to consider in short:
@@ Line 81: / Line 92: @@
 Tools like DokuWiki, SharePoint, Confluence enterprise can be used to make it easier to collaborate in the documentation. \\
+\\
-Is the tool ok to be in the ‘cloud’? Or is the data so sensitive that it should be a locally placed tool? \\
+Is the tool ok to be in the ‘cloud’? Or is the data so sensitive that it should be a locally placed tool?
+Like for all tools the easy to use and level of technical skills of the contributors needs to be assessed. Is the wiki path with all entries done with wiki-markup code? Or is a WYSIWYG (What You See Is What You Get) editor needed? \\
-Like for all tools the easy to use and level of technical skills of the contributors needs to be assessed. Is the wiki path with all entries done with wiki-markup code? Or is a WYSIWYG (What You See Is What You Get) editor needed?\\
+\\
 Ease of use should be one part of the choice of tool. \\
+\\
 If the content of the documents is of a sensitive sort. Then a granular restriction function should be implemented. Identity and Access Management (IAM) should always be part of the process of choosing the collaboration tool. \\
+\\
+=== Choosing a tool ===
+A thing to keep in mind is to start with how! \\
+\\
+How do you want the documentation and then try to find a tool to work with the how. Not the other way around, I.e., implement a tool and then try to make it work.\\
+The tool should be a help to the documentation not the thing you need to rewrite your policy for to make it work. Also, the tool must be something that everyone works with. There cannot be a college that “goes their own way” and uses other tools for documentation.\\
+Documentation should be easily accessible and easily read for the duration the documentation is valid. This can be a problem if the documentation is written in a prosperity format (or specific program) that is no longer accessible or readable. \\
+\\
+=== Update or not ===
+So should you update the documentation? \\
+\\
+The answer is almost always yes. The documentation is a “living” document. That means that constantly updating is needed. And so is the case with the most documentation. There are changes in what the document describes that needs to be updated in the documentation. \\
+==== Chapter 4 – Contributors ====
+There are different kind of contributors. I have chosen to split them in voluntary- and non voluntary contributors. Description of the two below. There will always be those who want to do it like it always was done. To not change anything if possible. And sure not all change is good but a big part of change is just that. \\
+\\
+=== Voluntary contributors ===
+This is the people that will just do the documentation and “fall in line”. Will use the presented tools and do the work. The easy ones. \\
+\\
+=== Non voluntary contributors ===
+This is the people that, buy some way, are against documentation or the tool(s) of documentation. Usually, these people’s aviation to the documentation or tool(s) for documentation is based form lack of knowledge. So, the logical way to make them more prone to document is to inform and up the knowledge regarding the importance of documentation. \\
+\\
+If there still are someone who do not want to do documentation in the new tool or documentation at all. Then someone with power in the company needs to put down the foot and make them get back in the que. \\
+\\
+But this can be a problem if some or several people do not contribute and can be a problem. This needs to be fixed as soon as possible. And via the managers of the organization. But not with only total force if it can be avoided. The best is to inform and educate to resolve the problems there can be. And maybe this will resolve all issues. \\
+\\
+Make sure to find those who are sceptic or against the tool/documentation as soon as possible to help them to find the benefits of the situation. \\
+\\
+=== Education ===
+Regardless of what kind of contributors you have, everyone will most probably need some kind of onboarding and education. It is much easier if there is a plan on onboarding and education from the start. Mabey even some how-tos and other documents to help the users start working with the new tool. \\
+==== Attachments ====
+The document as docx \\
+{{ :tipsandtricks:regarding_documentation.docx |}} \\
+and pdf format. \\
+{{ :tipsandtricks:regarding_documentation.pdf |}} \\