From 1592680085f5550dfe4f6ac1195c55cfce0a1f2f Mon Sep 17 00:00:00 2001 From: Jan Jambor Date: Tue, 14 May 2024 17:12:01 +0200 Subject: [PATCH] update: Improve onboarding documentation and include lessons learned from customer projects. --- agile-working.md | 11 +++++++++-- documentation-guidelines.md | 4 ++++ faq.md | 2 +- getting-started.md | 23 +++++++++++++++++++++++ welcome.md | 4 +--- 5 files changed, 38 insertions(+), 6 deletions(-) diff --git a/agile-working.md b/agile-working.md index 879e7da..83d995d 100644 --- a/agile-working.md +++ b/agile-working.md @@ -10,9 +10,16 @@ Tools: MS Teams Channel ## Documentation -Everyone must have independent access to documentation, including specifications, decissions, and changes. We aim to work in a decentralized and asynchronous manner. Each individual should always be able to access all necessary information. +Everyone must have independent access to documentation, including specifications, decissions, and changes. We aim to work in a decentralized and asynchronous manner. Each individual should always be able to access all necessary information. We see documentation as a joint effort of all members and everybody should always improve documentation as needed. For some guidlines see [Documentation Guiidlines](documentation-guidelines.md), these should be rather interpreted as code of conduct than strict rules. -Tools: Azure DevOps Repos +Tools: Azure DevOps Repos and Wikis + +## Meeting Minutes + +Suggestion JJ: +Meeting notes are centralized taken as tasks in Azure DevOps. Everybody is responsible for them. If you hear something in a meeting that is relevant for you: add it as a comment during the meeting, after the meeting. The meeting minute tasks don't need a parent. They should follow a template (to be defined) and can be linked to Stories and other work items like Issues (Impediments) which have been discussed during the meeting. + +Tools: Azure Boards Task ## The PI and sprints diff --git a/documentation-guidelines.md b/documentation-guidelines.md index ada584d..a3a2dd7 100644 --- a/documentation-guidelines.md +++ b/documentation-guidelines.md @@ -2,6 +2,10 @@ Best practices and guidelines for writing code documentation. +## Formats + +All documentation should be easy maintain and accessible. Easy formats should be preffered over more complex ones. + ## Release Notes The idea is to get rather automated release notes. To have this as easy as possible, we need: diff --git a/faq.md b/faq.md index 6e128db..6d5e37c 100644 --- a/faq.md +++ b/faq.md @@ -1,3 +1,3 @@ # Frequently Asked Questions -Suggestion JJ: Frequently asked questions by new developers. Here we display a link to a shared query displaying all work items of type task tagged with `FAQ`. +Suggestion JJ: Frequently asked questions by new developers. Here we display a link to a shared query displaying all work items of type task tagged with `FAQ`. The goal of doing so is, that we don't want to maintain a rather static markdown file and we want to be able to link FAQ entries to eg. Bug work items, meeting notes and so on. diff --git a/getting-started.md b/getting-started.md index 086d8e3..23c597a 100644 --- a/getting-started.md +++ b/getting-started.md @@ -3,3 +3,26 @@ Initial setup instructions for development environments. List and explanation of development tools used in our team. We should automate this as much as possible e.g. by providing an ansible playbook. + +## Setup git + +As we are relying on tracability, we are enforcing the use of proper usernames in git. If you are only working with Ypsomed repositories, you can use the following commands to set up your global git configuration: + +```bash +git config --global user.name "FIRST_NAME LAST_NAME" +git config --global user.email "ABBREVIATION@ypsomed.com" +``` + +If you are also working in other contexts, it is recommended to purge the global configuration and set it up for each repository individually. You can do this by running the following commands once: + +```bash +git config --global --unset user.name +git config --global --unset user.email +``` + +And then in each repository set up individual configuration: + +```bash +git config user.name "FIRST_NAME LAST_NAME" +git config user.email "ABBREVIATION@ypsomed.com" +``` diff --git a/welcome.md b/welcome.md index e4259fe..8c5ad41 100644 --- a/welcome.md +++ b/welcome.md @@ -2,8 +2,6 @@ Welcome message and introduction to the wiki. -## Cloud Stream Team Structure +## Team Structure Breakdown of the team's structure and roles. - -Link to orgmanager.