From 0373d155bad44126b573135c3649468f883f6e38 Mon Sep 17 00:00:00 2001 From: Jakub Riegel Date: Tue, 3 Oct 2023 16:55:42 +0200 Subject: [PATCH 1/7] Add note about data in RDT docs --- docs/README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/README.md b/docs/README.md index 80a6895a019b..f061e5e0286a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,6 +3,9 @@ We use [Sphinx] for creating the Artemis documentation using [reStructuredText] (RST). To get started with RST, check out the [Quickstart] or this [cheatsheet]. +> [!IMPORTANT] +> Artemis documentation must use real examples and personas and must avoid the use of test data. Sample personas accounts to be use in production for creating screenshots are listed [here](https://confluence.ase.in.tum.de/display/ArTEMiS/Random+Personas). + ## Documentation Hosting [Read the Docs] (RtD) hosts the [Artemis documentation] for the `develop` (latest) branch, as well as for From 15fb823407e00266489ba6c97bf4af8d127080c8 Mon Sep 17 00:00:00 2001 From: Jakub Riegel Date: Tue, 3 Oct 2023 18:05:36 +0200 Subject: [PATCH 2/7] add more extensive sample data and personas docs --- docs/README.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/README.md b/docs/README.md index f061e5e0286a..78d04e9a6fab 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,8 +3,24 @@ We use [Sphinx] for creating the Artemis documentation using [reStructuredText] (RST). To get started with RST, check out the [Quickstart] or this [cheatsheet]. -> [!IMPORTANT] -> Artemis documentation must use real examples and personas and must avoid the use of test data. Sample personas accounts to be use in production for creating screenshots are listed [here](https://confluence.ase.in.tum.de/display/ArTEMiS/Random+Personas). +## Sample Data & Personas +Artemis documentation must use realistic examples and personas and must avoid the use of test data. + +Using familiar information in the documentation is crucial because it simplifies the learning process for new users and shortents . Real-world scenarios demonstrate to users how to apply specific features within their own context, whereas test data can be misleading and fails to mirror real use cases. Realistic examples and personas provide clarity and relevance, ensuring users can effectively understand and utilize Artemis. + +Well defined personas are vital for the development process. They not only help readaers to understad the documentation, but also allow developers to better understand Artemis and its users. Personas are used by many organisations, two blog posts with introduction and motivation for the topic are presented below: +- [Using Personas During Design and Documentation](https://www.uxmatters.com/mt/archives/2010/10/using-personas-during-design-and-documentation.php) +- [Customer Personas: How to Write Them and Why You Need Them in Agile Software Development](https://community.atlassian.com/t5/App-Central/Customer-Personas-How-to-Write-Them-and-Why-You-Need-Them-in/ba-p/759228) + +Screenshots included in Artemis documentation **must** present realistic data. That includes but is not limited to: +- realistic user, course and exercise names +- realic text passages, like submissions contents and problem statements + +Screenshots included in Artemis documentation **must not** present any test data or server infomation. That includes but is not limited to: +- `Test Server` and `Development` labels +- test user, course and exercise names +- _Lorem ipsum_ and mock text passages, like submissions contents and problem statements +- test server and `localhost` domains ## Documentation Hosting From 769683a00ff893c82a857b15e5b84da7453815b0 Mon Sep 17 00:00:00 2001 From: Jakub Riegel Date: Tue, 3 Oct 2023 19:36:43 +0200 Subject: [PATCH 3/7] remove irrelevant text and passive voice --- docs/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/README.md b/docs/README.md index 78d04e9a6fab..b164c99245dc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,9 +6,9 @@ To get started with RST, check out the [Quickstart] or this [cheatsheet]. ## Sample Data & Personas Artemis documentation must use realistic examples and personas and must avoid the use of test data. -Using familiar information in the documentation is crucial because it simplifies the learning process for new users and shortents . Real-world scenarios demonstrate to users how to apply specific features within their own context, whereas test data can be misleading and fails to mirror real use cases. Realistic examples and personas provide clarity and relevance, ensuring users can effectively understand and utilize Artemis. +Using familiar information in the documentation is crucial because it simplifies the learning process for new users. Real-world scenarios demonstrate to users how to apply specific features within their own context, whereas test data can be misleading and fails to mirror real use cases. Realistic examples and personas provide clarity and relevance, ensuring users can effectively understand and utilize Artemis. -Well defined personas are vital for the development process. They not only help readaers to understad the documentation, but also allow developers to better understand Artemis and its users. Personas are used by many organisations, two blog posts with introduction and motivation for the topic are presented below: +Well defined personas are vital for the development process. They not only help readaers to understad the documentation, but also allow developers to better understand Artemis and its users. Personas are used by many organisations, the two blog posts below contain additional introduction and motivation for the topic: - [Using Personas During Design and Documentation](https://www.uxmatters.com/mt/archives/2010/10/using-personas-during-design-and-documentation.php) - [Customer Personas: How to Write Them and Why You Need Them in Agile Software Development](https://community.atlassian.com/t5/App-Central/Customer-Personas-How-to-Write-Them-and-Why-You-Need-Them-in/ba-p/759228) From 0b2a4576e6161cb47ee2ebacf639cd4a54ca140d Mon Sep 17 00:00:00 2001 From: Jakub Riegel Date: Tue, 3 Oct 2023 19:47:10 +0200 Subject: [PATCH 4/7] remove passive voice --- docs/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/README.md b/docs/README.md index b164c99245dc..c353ec105cb2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,9 +6,9 @@ To get started with RST, check out the [Quickstart] or this [cheatsheet]. ## Sample Data & Personas Artemis documentation must use realistic examples and personas and must avoid the use of test data. -Using familiar information in the documentation is crucial because it simplifies the learning process for new users. Real-world scenarios demonstrate to users how to apply specific features within their own context, whereas test data can be misleading and fails to mirror real use cases. Realistic examples and personas provide clarity and relevance, ensuring users can effectively understand and utilize Artemis. +Using familiar information in the documentation is crucial because it simplifies the learning process for new users. Real-world scenarios demonstrate to users how to apply specific features within their own context, whereas test data can mislead and fails to reflect real use cases. Realistic examples and personas provide clarity and relevance, ensuring users can effectively understand and utilize Artemis. -Well defined personas are vital for the development process. They not only help readaers to understad the documentation, but also allow developers to better understand Artemis and its users. Personas are used by many organisations, the two blog posts below contain additional introduction and motivation for the topic: +Well defined personas are vital for the development process. They not only help readaers to understad the documentation, but also allow developers to better understand Artemis and its users. Many organisations use personas, the two blog posts below contain additional introduction and motivation for the topic: - [Using Personas During Design and Documentation](https://www.uxmatters.com/mt/archives/2010/10/using-personas-during-design-and-documentation.php) - [Customer Personas: How to Write Them and Why You Need Them in Agile Software Development](https://community.atlassian.com/t5/App-Central/Customer-Personas-How-to-Write-Them-and-Why-You-Need-Them-in/ba-p/759228) From 30688d47c9dc9b648e484f6890957ef26f97fb69 Mon Sep 17 00:00:00 2001 From: Jakub Riegel Date: Tue, 3 Oct 2023 23:45:47 +0200 Subject: [PATCH 5/7] fix typos Co-authored-by: Benedikt Fein --- docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index c353ec105cb2..4bad67664b9c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,7 +16,7 @@ Screenshots included in Artemis documentation **must** present realistic data. T - realistic user, course and exercise names - realic text passages, like submissions contents and problem statements -Screenshots included in Artemis documentation **must not** present any test data or server infomation. That includes but is not limited to: +Screenshots included in Artemis documentation **must not** present any test data or server information. That includes but is not limited to: - `Test Server` and `Development` labels - test user, course and exercise names - _Lorem ipsum_ and mock text passages, like submissions contents and problem statements From d681e44548f965d384446d2b116410c3aff66764 Mon Sep 17 00:00:00 2001 From: Jakub Riegel Date: Tue, 3 Oct 2023 23:45:55 +0200 Subject: [PATCH 6/7] fix typos Co-authored-by: Benedikt Fein --- docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 4bad67664b9c..700d7b73eb17 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,7 +14,7 @@ Well defined personas are vital for the development process. They not only help Screenshots included in Artemis documentation **must** present realistic data. That includes but is not limited to: - realistic user, course and exercise names -- realic text passages, like submissions contents and problem statements +- realistic text passages, like submissions contents and problem statements Screenshots included in Artemis documentation **must not** present any test data or server information. That includes but is not limited to: - `Test Server` and `Development` labels From dd4e25078ca0f1cad4efde5a38021e74427fb2b8 Mon Sep 17 00:00:00 2001 From: Jakub Riegel Date: Tue, 3 Oct 2023 23:46:02 +0200 Subject: [PATCH 7/7] fix typos Co-authored-by: Benedikt Fein --- docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 700d7b73eb17..22d3cd33745b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,7 +8,7 @@ Artemis documentation must use realistic examples and personas and must avoid th Using familiar information in the documentation is crucial because it simplifies the learning process for new users. Real-world scenarios demonstrate to users how to apply specific features within their own context, whereas test data can mislead and fails to reflect real use cases. Realistic examples and personas provide clarity and relevance, ensuring users can effectively understand and utilize Artemis. -Well defined personas are vital for the development process. They not only help readaers to understad the documentation, but also allow developers to better understand Artemis and its users. Many organisations use personas, the two blog posts below contain additional introduction and motivation for the topic: +Well-defined personas are vital for the development process. They not only help readers to understand the documentation, but also allow developers to better understand Artemis and its users. Many organizations use personas, the two blog posts below contain additional introduction and motivation for the topic: - [Using Personas During Design and Documentation](https://www.uxmatters.com/mt/archives/2010/10/using-personas-during-design-and-documentation.php) - [Customer Personas: How to Write Them and Why You Need Them in Agile Software Development](https://community.atlassian.com/t5/App-Central/Customer-Personas-How-to-Write-Them-and-Why-You-Need-Them-in/ba-p/759228)