Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Development: Add note about data used in Artemis docs #7308

Merged
merged 8 commits into from
Oct 4, 2023
Merged

Development: Add note about data used in Artemis docs #7308

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
0373d15
Add note about data in RDT docs
jakubriegel Oct 3, 2023
15fb823
add more extensive sample data and personas docs
jakubriegel Oct 3, 2023
769683a
remove irrelevant text and passive voice
jakubriegel Oct 3, 2023
0b2a457
remove passive voice
jakubriegel Oct 3, 2023
30688d4
fix typos
jakubriegel Oct 3, 2023
d681e44
fix typos
jakubriegel Oct 3, 2023
dd4e250
fix typos
jakubriegel Oct 3, 2023
9e0a729
Merge branch 'develop' into screenshots-in-rtd-docs-data
jakubriegel Oct 3, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading