Differences

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

--- kb:bestpractices:documentation [2024/03/11 11:19] – ↷ Links adapted because of a move operation joerg.hampel
+++ kb:bestpractices:documentation [2025/05/19 14:59] (current) – manuel.sebald
@@ Line 1: / Line 1: @@
 ====== Documentation ======
-For a successful project, the documentation is as important as testing the code. The intention of this section is to provide basic guidelines and tips to write good documentation, for HSE (in this DocuWiki) and for our customers.
+Documentation is an important ingredient to success. On these pages, we share ideas and templates for creating documentation for projects as well as documentation for processes, workflows and tools.
-These better practices are mainly inspired by [[https://docs-guide.readthedocs.io/en/latest/|The Hitchhiker's Guide to Documentation!]]. For a more comprehensive guide about documenting software projects, take a look at it.
+===== Contents =====
+{{indexmenu>:kb:bestpractices:documentation#1|tsort nsort}}
-===== Documentation Types =====
+----
-First of all, be clear about what you want to write. The type of the documentation heavily influences the structure and style. Usually we use three different types:
+<WRAP center round tip 100%>
+**For generating documentation from your LabVIEW code, make sure to check out the [[kb:labview-toolkits:antidoc|Antidoc Toolkit]].**
+</WRAP>
-  * Tutorial (aka "Quick Start" or "Getting Started")
+----
-  * Guide (more comprehensive)
-  * Reference (aka API documentation)
+===== Project Documentation =====
-==== Tutorial ====
+Project specific documentation shall be included in the Git repository under the folder ''/Documentation''. Subfolders can be used to distinguish between documentation types, e.g. auto-generated code documentation, code architecture, ULM diagrams etc.
-Tutorials are like a front door or a shop window. They demonstrate how your project "feels".
-New users usually first read the "Quick Start" section. They want a simple example to see how this library or application can be used. Give the user a quick lift.
+==== Tooling ====
-See also https://docs-guide.readthedocs.io/en/latest/tutorials/
+For all types of diagrams, we use the free and for all platforms available tool [[https://www.drawio.com/|daraw.io]]. It can be used directly from the Browser, or as a desktop app. Link to the most recent version: https://get.diagrams.net/.
+Online tools that work in the cloud (e.g. Canva, MS365, ...) shall be avoided because of security and confidentially issues.
-==== Guide ====
+<WRAP center round note important 100%>
+**Do not store confidential customer data in untrusted cloud services!**
+</WRAP>
-Should be a comprehensive documentation of the project. Main aspects are:
-  * show the vast majority of possible options (but should not show all possible options -- that is the task for reference),
-  * show how all concepts fit together,
-  * answer the question "why?".
-==== Reference ====
-References should answer the question "how?". For this, it must include every detail. For example, an API reference documents every public function and every parameter. It can contain short code examples, too.
-A reference is what our [[code:commercial:rat:tools:documentr|RAT Documentr]] generates.
-===== Writing Documentation =====
-Good advices for writing documentation can be found here: https://docs-guide.readthedocs.io/en/latest/writing/
-===== Documentation Structure =====
-To find and maintain a good structure is critical for good documentation. For this, Read The Docs provides us a good help, too: https://docs-guide.readthedocs.io/en/latest/structure/
-For our DokuWiki we should maintain a set of templates. These tempates provide a common structure for each type of documentation and makes it easier to start (no "blank page" phenomena).
-===== Style =====
-Last but not least, you can find helpful advice for a good writing style here: https://docs-guide.readthedocs.io/en/latest/style/
-===== HSE DokuWiki Templates =====
-{{indexmenu>kb:bestpractices:documentation|tsort nsort}}
-//HSE-Internal: [[organization:internal-kb:sw-dev:tools-libraries-in-dokuwiki|Tools/Libraries DW Structure]]//