diff --git a/docs/README.md b/docs/README.md index 80a6895a019b..22d3cd33745b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,6 +3,25 @@ We use [Sphinx] for creating the Artemis documentation using [reStructuredText] (RST). 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 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 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) + +Screenshots included in Artemis documentation **must** present realistic data. That includes but is not limited to: +- realistic user, course and exercise names +- 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 +- 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 [Read the Docs] (RtD) hosts the [Artemis documentation] for the `develop` (latest) branch, as well as for