Redmine usage guidelines

These guidelines for using the Redmine project management system aim at enhancing team efficiency, communication and documentation. Here are key topics to consider, including the emphasis on content-focused communication:

0. How to participate:

• Clarify with Jan Meier-Kolthoff how and in which way you want to participate in which Redmine project. Once this is done, use the 'register'-button in the top-right of the landing page. Afterwards, write a short note to Jan and he will add you to the respective project(s).

1. Content-Focused Communication:

• Focus on the subject matter (content, new information, problems, questions, progress etc.) when creating or updating tickets.
• Avoid salutations like "Hello [Name]" and sign-offs such as "Thank you [Name]" to maintain clarity and professionalism.

2. Clear and Concise Issue Reporting:

• Provide a clear and concise description, including steps to reproduce the problem, expected outcomes, and relevant attachments (regarding files please see item "File Management" below).
• If larger text blocks are necessary, put them in the project's dedicated Wiki page and link it from within the ticket.

3. Avoid Inserting (Big) Chunks of AI-Generated Content:

• Write updates using your own words. The project members want to read your updates, not ones generated by ChatGPT.
• AI content can often be verbose, incorrect, or unclear .
• AI content is oftentimes not focused and contains superfluous information
• Increased ownership : When issues are populated by project members on their own (read: manually, no AI use), there is a greater sense of ownership and responsibility.
• Accountability : If issues are created with AI content, it could be harder to track the responsibility for the issue's resolution. Humans can clearly document their decisions, actions, and rationale for why the issue needs attention, creating a trail of accountability.
• Always check AI content for correctness, clarity, and conciseness.

4. Avoid attaching many files (e.g. images, tables) inside an issue:

• A Redmine issue/ticket does not replace a project result report
• Whenever possible, please link to a shared Nextcloud folder (location has to be agreed upon with the other project members) instead of uploading figures, tables, or large files directly into a Redmine issue.
• Benefits are: Easier updates to results without needing to re-upload new versions, cCentralized storage, reducing file clutter in issues.
• Small screenshots or illustrative attachments that are essential for understanding the issue are, of course, still welcome where appropriate.
• also see item "File Management" below

5. Consistent Use of Trackers and Statuses:

• Define and consistently use trackers (e.g., Bug, Feature, Task) and statuses (e.g., New, In Progress, Resolved, Closed).
• Set a status to "closed" once a ticket is done.

6. Role-Based Access Control:

• Ensure that roles (e.g., Manager, Developer, Reporter) are defined so everyone has the necessary permissions without compromising project integrity.

7. Time Tracking and Reporting:

• Regularly update time-related fields on tickets to log time spent on tasks.
• This helps generate accurate reports on project progress and resource allocation.

8. Documentation and Knowledge Sharing:

• Document project-specific information like installation guidelines in the project-specific Wiki for knowledge sharing.
• For broader Wiki content, consider adding it to a global documentation project.

9. Integration with Version Control Systems:

• Do not use Redmine-based version control but stick to the existing Gitlab
• Properly link to GitLab for specific commits, bug fixes, and releases.

10. Regular Use of Gantt Charts and Calendars:

• Utilize Gantt charts and calendars to visualize project timelines, deadlines, and dependencies for effective planning and monitoring.

11. Email Notifications and Updates:

• Check if email notifications are working and set up a rule to sort Redmine emails into a specific folder in your email account.
• This helps keep team members informed and ensures timely responses and actions, especially when being away on business trips or the like.

12. Avoiding Multiple Issue Trackers and Fragmentation:

• Use Redmine as the sole platform for managing and tracking project-related issues, tasks, and bugs.
• Avoid creating links to posts in external platforms like Slack to prevent data fragmentation.

13. File Management:

• Be careful with uploading files containing sensitive data.
• Avoid storing large files directly in Redmine.
• Do not add screenshots or other images when the content can also be inserted in text form (e.g. copy relevant terminal output and insert it into a code block)
• Ensure no redundancy occurs when uploading files (e.g., if providing an Excel sheet, avoid also uploading DOCX or PDF versions, as these can be generated from Excel).
• Refrain from adding multiple versions of the same file within a ticket's updates.
• Files only needed for the duration of a specific project should be curated in the "Files" section of that project for easy retrieval.
• Files of general importance to the ABC or the Chair should be organized in a shared Nextcloud repository.
• Provide links to code or files in the GitLab repository rather than uploading them directly to Redmine.

Feedback on these guidelines¶

Please send any type of feedback (changes, chocolate cookies etc.) to Jan.