From 1a0084754e10c58a5e41da5a106d3d7eb8791ab4 Mon Sep 17 00:00:00 2001 From: Tilman Justen Date: Tue, 29 Sep 2020 10:26:39 +0200 Subject: [PATCH 1/5] add documentation day --- general/documentation-day.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 general/documentation-day.md diff --git a/general/documentation-day.md b/general/documentation-day.md new file mode 100644 index 0000000..c27426d --- /dev/null +++ b/general/documentation-day.md @@ -0,0 +1,19 @@ +# Documentation Day + +## Goals of the Documentation Day + +The general idea is that every project has a regular day when the documentation is checked. The goal is to have **well maintained documentations with all necessary and up-to-date information**. + +The main goal of the Documentation Day is to **establish and maintain confidence in the documentation**. + +## Necessity, Frequency and Duration + +The lifespan of a project, the frequency of code contributions as well as the number of contributors are factors for the necessity and frequency of a Documentation Day. If the development from start to finish is about 3 weeks or code contributions are not regular enough, a Documentation Day is not necessary. In this case the documentation should be checked as part of the QA phase. + +If the number of developers contributing code + +* **is 2** a Documentation Day should be planed every **4 weeks**, +* **is up to 6** a Documentation Day should be planed every **3 weeks** and +* **is larger than 6** a Documentation Day should be planed **within the sprint cycle**. + +When doing documentation days do them time boxed. One hour is a good starting point. Within this period do whatever you can do. You don’t have to create or change the whole documentation at once. Eat slowly, bite after bite. From caa6f3b53569feae01ffa77b72b5245e92d349df Mon Sep 17 00:00:00 2001 From: Tilman Justen Date: Tue, 29 Sep 2020 10:27:17 +0200 Subject: [PATCH 2/5] add documentation guide --- general/documentation-guide.md | 92 ++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 general/documentation-guide.md diff --git a/general/documentation-guide.md b/general/documentation-guide.md new file mode 100644 index 0000000..9e4f9fa --- /dev/null +++ b/general/documentation-guide.md @@ -0,0 +1,92 @@ +# Documentation Guide + +This is a brief guide on how to document different types of information within software projects. Every project has different key aspects so build your own toolbox out of it. This guide covers general technical and non technical documentation. It does not deal with documentation in code. + +First of all writing documentation is more kind of a mindset than everything else. It is about you and your work and less how your (team’s) workflows are or which tools you use. Starting a documentation is the easy part. The hard part comes with maintenance. No doubt you get the easy part on yourself. This guide takes you on the journey to get the hard part easy too. + +### Where to put the documentation + +Ask yourself who should read the documentation. For technical people the readme should be okay. For non technical people Confluence (or project wiki) should fit your needs. Keep in mind that you can start where you are. If there is a Readme.md take it. You can move the contents later within a documentation (or readme) day. + +### How to maintain a documentation + +To keep your documentation right, make it part of your personal and your team's development process and mindset. Create rules that fit your and your team’s needs: No feature merge without documentation, organize documentation days, etc. +Adapt your team's workflows and take information that still exists when starting the documentation. User stories and tickets are a good starting point. You just have to move them to your documentation place and give them a review when development has finished. +Everyone who is developing software does some kind of technical concept. Write it down and give it a review when development has finished. + +Keep in mind that your documentation does not have to be perfect. Your documentation has to be good or at least okay. It should be good to read. It may be fun to read. It never has to be wrong over a period of time. + +**Focus on the content. Always.** + +## Who and How + +Assigning all involved developers to execute a Documentation Day, one after another, is a good idea. Introducing new developers by having them execute the Documentation Day will provide great insight and valuable feedback, as well as asking developers who are not involved in the project. + +The following steps are one possible way for the Documentation Day: + +tbd + +If possible, fix all identified problems directly and update the documentation regardingly. Otherwise try to schedule the issues to have them fixed at least until the next Documentation Day. + +## When + +The most important rule is to document regularly. Every project has many suitable possibilities when documentation can happen. Or at least when to check if a documentation is needed. + +Sprint Reviews +Start of feature development +End of feature development +etc. + +The best choice you can make is to take what you already have. As mentioned in section [How to maintain a documentation](#how-to-maintain-a-documentation), documenting is more a task of collecting existing information as producing content from scratch. Use what you have: User stories, task descriptions, estimations. + +When you start documenting, we recommend that you nominate a responsible person. + +### What to document + +#### Project setup + +The goal is to get every new developer to run the project setup on its own. We highly recommend documenting the project setup within the Readme file of your project and [applying the Readme Day](https://github.com/avenga/coding-guidelines/blob/master/general/readme-day.md). + +#### (System) Architecture and Infrastructure + +The documentation of the system architecture and infrastructure describes the big picture of an application. You don’t need to go too much into detail. The goal is to give the viewer an idea of which systems are involved. The system architecture could be a good starting point to dive deeper. + +> **Tip:** Use flow charts to visualize the system architecture. + +Containers & Volumes +Environments +Deployment pipeline +Services +3rd party dependencies + +#### APIs + +We highly recommend describing your APIs with an OpenAPI (former Swagger) specification. The specification acts as a single source of truth for your system APIs and technical dependencies outside of the project too. + +#### Features Over Time + +tbd + +(one single point of truth where anybody can see the current requirements for a given feature. Should solve problem that requirements are spread across JIRA-Tickets) + +#### Git + + (contribution.md in repo? Confluence?) + +Branche Model, e.g. [GitFlow]() +[Reviews](https://github.com/avenga/coding-guidelines/blob/master/general/Code-review-rules.md) +[Git Guidelines](https://github.com/avenga/coding-guidelines/blob/master/general/avenga-git-guidelines.md) + +#### Ticket-Flow? + +QA +UX Handover and Review +DEV + +#### Definition of Done? + +Describe your team's definition of done. + +#### Project Sheet + +[Project Sheet](https://github.com/avenga/coding-guidelines/blob/master/doc-templates/PROJECT_SHEET.md) From 5fdfe502d84f0e13d5a7d66ab732f6bd05467ce1 Mon Sep 17 00:00:00 2001 From: Tilman Justen Date: Fri, 22 Jan 2021 08:50:55 +0100 Subject: [PATCH 3/5] add documentation day and documentation guidelines to the index --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 41d0bab..04ec24a 100644 --- a/README.md +++ b/README.md @@ -12,3 +12,5 @@ Guidelines, recommendations, linting, formating and IDE configs provided and use - [Code Review Rules](general/Code-review-rules.md) - [Front-end Security Guidelines](general/front-end-security-guidelines.md) - [Coding Tools Configurations](general/coding-tools-configs.md) +- [Documentation Day](general/documentation-day.md) +- [Documentation Guidelines](general/documentation-guide.md) From 8c8277776e4d7ae0b30e08a2791c76496ebacca0 Mon Sep 17 00:00:00 2001 From: Tilman Justen Date: Thu, 6 Jul 2023 15:07:43 +0200 Subject: [PATCH 4/5] extend and sharpen the documentation day and documentation guide documentation --- general/documentation-day.md | 10 ++++ general/documentation-guide.md | 84 +++++++++++++++------------------- 2 files changed, 48 insertions(+), 46 deletions(-) diff --git a/general/documentation-day.md b/general/documentation-day.md index c27426d..261b358 100644 --- a/general/documentation-day.md +++ b/general/documentation-day.md @@ -6,6 +6,16 @@ The general idea is that every project has a regular day when the documentation The main goal of the Documentation Day is to **establish and maintain confidence in the documentation**. +## Where to Start + +Assigning all involved developers to execute a Documentation Day, one after another, is a good idea. Introducing new developers by having them execute the Documentation Day will provide great insight and valuable feedback, as well as asking developers who are not involved in the project. + +The following steps are one possible way for the Documentation Day: + +tbd + +If possible, fix all identified problems directly and update the documentation regardingly. Otherwise try to schedule the issues to have them fixed at least until the next Documentation Day. + ## Necessity, Frequency and Duration The lifespan of a project, the frequency of code contributions as well as the number of contributors are factors for the necessity and frequency of a Documentation Day. If the development from start to finish is about 3 weeks or code contributions are not regular enough, a Documentation Day is not necessary. In this case the documentation should be checked as part of the QA phase. diff --git a/general/documentation-guide.md b/general/documentation-guide.md index 9e4f9fa..b47b6ef 100644 --- a/general/documentation-guide.md +++ b/general/documentation-guide.md @@ -1,14 +1,17 @@ # Documentation Guide -This is a brief guide on how to document different types of information within software projects. Every project has different key aspects so build your own toolbox out of it. This guide covers general technical and non technical documentation. It does not deal with documentation in code. +This is a brief guide on how to document different types of information within software projects. Every project has different key aspect. So build your own toolbox out of it. This guide covers general technical and non technical documentation. It does not deal with documentation in code. First of all writing documentation is more kind of a mindset than everything else. It is about you and your work and less how your (team’s) workflows are or which tools you use. Starting a documentation is the easy part. The hard part comes with maintenance. No doubt you get the easy part on yourself. This guide takes you on the journey to get the hard part easy too. -### Where to put the documentation +## Where to put the documentation -Ask yourself who should read the documentation. For technical people the readme should be okay. For non technical people Confluence (or project wiki) should fit your needs. Keep in mind that you can start where you are. If there is a Readme.md take it. You can move the contents later within a documentation (or readme) day. +Ask yourself who should read the documentation. For technical people the readme is the perfect entry point. Which can be expanded to a simple file system based structure of markdown files. +For non technical people confluence (or project wiki) should fit your needs. Keep in mind that you can start where you are. If there is a Readme.md take it. You can move the contents later within a documentation (or readme) day. -### How to maintain a documentation +Feel free to use our [readme template as a starter.](../doc-templates/README.md) + +## How to maintain a documentation To keep your documentation right, make it part of your personal and your team's development process and mindset. Create rules that fit your and your team’s needs: No feature merge without documentation, organize documentation days, etc. Adapt your team's workflows and take information that still exists when starting the documentation. User stories and tickets are a good starting point. You just have to move them to your documentation place and give them a review when development has finished. @@ -16,77 +19,66 @@ Everyone who is developing software does some kind of technical concept. Write i Keep in mind that your documentation does not have to be perfect. Your documentation has to be good or at least okay. It should be good to read. It may be fun to read. It never has to be wrong over a period of time. -**Focus on the content. Always.** +**Focus on the content. _Always_.** ## Who and How -Assigning all involved developers to execute a Documentation Day, one after another, is a good idea. Introducing new developers by having them execute the Documentation Day will provide great insight and valuable feedback, as well as asking developers who are not involved in the project. - -The following steps are one possible way for the Documentation Day: - -tbd - -If possible, fix all identified problems directly and update the documentation regardingly. Otherwise try to schedule the issues to have them fixed at least until the next Documentation Day. +Everyone who's involved in project development should participate. As a rule of thumb every code change should be accompanied by a documentation change. ## When The most important rule is to document regularly. Every project has many suitable possibilities when documentation can happen. Or at least when to check if a documentation is needed. -Sprint Reviews -Start of feature development -End of feature development -etc. +- Code changes +- Sprint reviews +- Start of feature development +- End of feature development The best choice you can make is to take what you already have. As mentioned in section [How to maintain a documentation](#how-to-maintain-a-documentation), documenting is more a task of collecting existing information as producing content from scratch. Use what you have: User stories, task descriptions, estimations. When you start documenting, we recommend that you nominate a responsible person. -### What to document +## What to document -#### Project setup +### Project setup The goal is to get every new developer to run the project setup on its own. We highly recommend documenting the project setup within the Readme file of your project and [applying the Readme Day](https://github.com/avenga/coding-guidelines/blob/master/general/readme-day.md). -#### (System) Architecture and Infrastructure +### System and Software Architecture -The documentation of the system architecture and infrastructure describes the big picture of an application. You don’t need to go too much into detail. The goal is to give the viewer an idea of which systems are involved. The system architecture could be a good starting point to dive deeper. +The documentation of the software and system architecture describes the big picture of an application. You don’t need to go too much into detail. The goal is to give the viewer an idea of which systems are involved. The system architecture could be a good starting point to dive deeper. > **Tip:** Use flow charts to visualize the system architecture. -Containers & Volumes -Environments -Deployment pipeline -Services -3rd party dependencies +- Containers & Volumes +- Environments +- Deployment pipeline +- Services +- 3rd party dependencies -#### APIs +### APIs We highly recommend describing your APIs with an OpenAPI (former Swagger) specification. The specification acts as a single source of truth for your system APIs and technical dependencies outside of the project too. -#### Features Over Time - -tbd - -(one single point of truth where anybody can see the current requirements for a given feature. Should solve problem that requirements are spread across JIRA-Tickets) - -#### Git - - (contribution.md in repo? Confluence?) +### Features Over Time -Branche Model, e.g. [GitFlow]() -[Reviews](https://github.com/avenga/coding-guidelines/blob/master/general/Code-review-rules.md) -[Git Guidelines](https://github.com/avenga/coding-guidelines/blob/master/general/avenga-git-guidelines.md) +Feature documentation should reflect the current state of requirements from a technical perspective. And how these requirements are fullfilled. You should extend the topics by actual examples and exceptions. Especially when no unit tests exists. -#### Ticket-Flow? +The feature documentation acts as single source of truth. -QA -UX Handover and Review -DEV +### Contributing -#### Definition of Done? +Tell the people how to contribute to the project. The contribution documentation usually consists of several topics. Best place to store the contribution documentation is the `CONTRIBUTING.md.` -Describe your team's definition of done. +- [git branch model and workflow](./avenga-git-guidelines.md) +) +- [merge request/code review rules](./Code-review-rules.md) +- definition of done +- the ticket workflow +- [coding tools config](./coding-tools-configs.md) +- handover rules to other project participants like QA oder UI/UX +- etc. -#### Project Sheet +### Project Sheet -[Project Sheet](https://github.com/avenga/coding-guidelines/blob/master/doc-templates/PROJECT_SHEET.md) +Use the [project sheet template](../doc-templates/PROJECT_SHEET.md) as a starting point. Where participants get the big picture of your project. From 2b76f1ae3d411bebef4e3935040041c1f79aac47 Mon Sep 17 00:00:00 2001 From: Tilman Justen Date: Thu, 6 Jul 2023 22:25:12 +0200 Subject: [PATCH 5/5] add examples of how to do the documentation day --- general/documentation-day.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/general/documentation-day.md b/general/documentation-day.md index 261b358..b218ef2 100644 --- a/general/documentation-day.md +++ b/general/documentation-day.md @@ -12,7 +12,17 @@ Assigning all involved developers to execute a Documentation Day, one after anot The following steps are one possible way for the Documentation Day: -tbd +1. Read the readme and contributing file to get a brief overview +2. Setup the project +3. Take an arbitrary task and start adding a feature or fixing a bug +4. Check the related documentation (if already exist). + +An alternative might be to focus on the documentation of a specific feature. + +1. Ask any project member to name three arbitrary features +2. Select your favourite dice and roll ... +3. Read the documentation of the feature your dice has chosen +4. Check for inconsistencies and incomprehensions. If possible, fix all identified problems directly and update the documentation regardingly. Otherwise try to schedule the issues to have them fixed at least until the next Documentation Day.