Skip to content

Contributing to EPICURE Documentation

Welcome to the EPICURE Knowledge Base! We welcome contributions from the HPC community to help make this resource valuable for everyone.

The live documentation is available at: https://docs-31e4a2.pages.it4i.eu/

⚠️ Important Deployment Notice: When your changes are merged into the main branch, they will be automatically deployed and made publicly available on the live documentation site. We strongly recommend having a second pair of eyes review your content through the GitLab merge request process before merging. See our Review Process section below for details.

Getting Started

Prerequisites

Before you begin, make sure you have:

  • A GitLab account with access to the EPICURE documentation repository
  • Basic knowledge of Markdown formatting
  • Git installed on your local machine
  • Python 3.8+ for local testing

Quick Start Workflow

  1. Fork or clone the repository
  2. Create a new branch for your contribution (use content/your-content-name)
  3. Add your content following our guidelines
  4. Test locally using MkDocs
  5. Submit a merge request for review (GitLab Merge Request Guide)
  6. Request peer review from a colleague or maintainer
  7. Address feedback if requested
  8. Content is automatically deployed upon merge to main

Recommended: Always have a second pair of eyes review your content through the GitLab merge request process before merging to ensure quality and catch any issues.

Content Types and Templates

How-To Guides

Step-by-step instructions for specific technical tasks.

Location: docs/articles/how-to/ Naming: Use descriptive, kebab-case filenames (e.g., gpu-memory-optimization.md)

Template:

---
title: Your Guide Title
description: Brief description of what this guide covers
tags: [tag1, tag2, tag3]
---

# Your Guide Title

Brief introduction explaining what readers will learn.

## Prerequisites

- List any requirements
- Software, access, or knowledge needed

## Step 1: First Major Step

Detailed instructions...

## Step 2: Next Step

More instructions...

## Troubleshooting

Common issues and solutions.

## Conclusion

Summary and next steps.

Case Studies

Real-world examples and implementations.

Location: docs/articles/case-studies/ Focus: Specific projects, performance improvements, or success stories

Template:

---
title: Case Study Title
description: Brief description of the case study
tags: [domain, system, technique]
---

# Case Study: Project Name

## Overview

Brief summary of the project and its goals.

## Challenge

What problem was being solved?

## Solution

How was it addressed?

## Implementation

Technical details of the implementation.

## Results

Measurable outcomes and performance improvements.

## Lessons Learned

Key takeaways and recommendations.

Best Practices

Expert guidelines and recommendations.

Location: docs/articles/best-practices/ Focus: General principles and proven approaches

Template:

---
title: Best Practice Title
description: Brief description
tags: [category, topic]
---

# Best Practice: Topic

## Overview

Why this practice matters.

## The Practice

Detailed explanation of the recommended approach.

## Benefits

Why following this practice helps.

## Implementation

How to apply this in practice.

## Common Pitfalls

What to avoid.

## Examples

Real-world examples or code snippets.

Code Snippets

Ready-to-use code examples.

Location: docs/articles/code-snippets/ Focus: Reusable code patterns and examples

Template:

---
title: Code Snippet Title
description: Brief description of what the code does
tags: [language, library, technique]
---

# Code Snippet: Purpose

## Overview

Brief explanation of what this code accomplishes.

## Code

\`\`\`language
// Your code here
\`\`\`

## Usage

How to use this code snippet.

## Variations

Alternative implementations or modifications.

## Related

Links to related snippets or documentation.

Content Guidelines

Writing Style

  • Clear and concise: Use simple, direct language
  • Action-oriented: Focus on what readers need to do
  • Structured: Use headings, lists, and code blocks effectively
  • Inclusive: Write for diverse technical backgrounds

Markdown Standards

  • Use consistent heading hierarchy (#, ##, ###)
  • Include frontmatter with title, description, and tags
  • Use code fences with language specification
  • Add blank lines around lists and code blocks
  • Include alt text for images

Technical Content

  • Test all code: Ensure examples work as written
  • Include prerequisites: List required software, access, or knowledge
  • Add context: Explain why something works, not just how
  • Reference systems: Specify which EuroHPC systems apply
  • Version information: Include relevant version numbers

Development Setup

Local Environment Setup

  1. Clone the repository:
git clone https://opencode.it4i.eu/epicure/docs.git
cd docs
  1. Create and activate a virtual environment:
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  1. Install dependencies:
pip install -r requirements.txt
  1. Start the local development server:
mkdocs serve
# or
python -m mkdocs serve

The documentation will be available at http://127.0.0.1:8000

Building for Production

mkdocs build
# or
python -m mkdocs build

Submission Process

Step 1: Create Your Content

  1. Choose the appropriate section (how-to, case-studies, best-practices, or code-snippets)
  2. Create a new .md file with a descriptive name
  3. Use the appropriate template from above
  4. Write your content following our guidelines

Step 2: Add Navigation (Optional)

For major new sections, you may need to update mkdocs.yml:

nav:
  - Knowledge Base:
      - How-To Guides:
          - articles/how-to/index.md
          - Your New Guide: articles/how-to/your-new-guide.md

Step 3: Test Locally

# Start local server
mkdocs serve

# View at http://127.0.0.1:8000
# Check your content renders correctly

Step 4: Submit for Review

  1. Create a branch: git checkout -b content/your-content-name
  2. Commit changes: git add . && git commit -m "Add guide on topic"
  3. Push branch: git push origin content/your-content-name
  4. Create merge request: Use GitLab's interface to submit for review

⚠️ Reminder: Once merged to main, your content will be automatically deployed to the live site within minutes.

Review Process

Peer Review Workflow

All contributions go through a peer review process to ensure quality and accuracy:

  1. Create a Merge Request: Submit your changes as a GitLab merge request
  2. Request Review: Ask a colleague or maintainer to review your content
  3. Address Feedback: Make any requested changes and updates
  4. Approval and Merge: Once approved, your content will be merged and automatically deployed

We strongly encourage peer review for all content, especially: - Technical tutorials and guides - System-specific documentation - Best practices and recommendations - Code examples and snippets

For detailed information on the GitLab merge request workflow, see the official GitLab documentation.

Content Review Criteria

All submissions go through a review process checking:

  1. Technical accuracy: Content is technically correct
  2. Clarity: Information is clear and well-structured
  3. Relevance: Content fits the knowledge base scope
  4. Quality: Writing meets our standards

Style Guide

File Naming

  • Use lowercase, kebab-case: memory-optimization-techniques.md
  • Be descriptive: pytorch-distributed-training-lumi.md
  • Avoid abbreviations unless widely known

Image Guidelines

  • Store images in docs/assets/images/
  • Use descriptive filenames
  • Optimize file sizes (prefer PNG for screenshots, JPG for photos)
  • Include alt text for accessibility

Code Examples

  • Test all code before submitting
  • Include necessary imports and dependencies
  • Use syntax highlighting with language specification
  • Provide context for code snippets
  • Include expected output when helpful
  • Use relative links for internal content
  • Verify external links are current and reliable
  • Prefer official documentation sources
  • Include link descriptions for clarity

Getting Help

Documentation Questions

  • Create an issue in the repository
  • Tag it with documentation label
  • Provide specific questions or feedback

Technical Support

  • For EPICURE-specific questions: Contact the support team
  • For general HPC questions: Use community resources
  • For urgent issues: Use appropriate support channels

Content Ideas

Not sure what to contribute? Here are some ideas:

  • Performance optimization techniques you've discovered
  • Debugging strategies for common HPC issues
  • Workflow improvements that saved time or resources
  • System-specific tips for EuroHPC machines
  • Software installation guides for complex packages
  • Scaling strategies for parallel applications

Code of Conduct

All contributors are expected to follow our Code of Conduct:

Be Respectful

  • Treat everyone with respect
  • Be open to feedback
  • Maintain a positive attitude

Be Professional

  • Keep discussions professional
  • Avoid personal attacks
  • Focus on technical merit

Be Collaborative

  • Work together to improve the knowledge base
  • Help each other learn and grow
  • Share knowledge generously

Maintenance and Updates

Keeping Content Current

  • Review your contributions periodically
  • Update for new software versions or system changes
  • Respond to user feedback and questions
  • Consider creating follow-up content

Community Engagement

  • Participate in content discussions
  • Provide feedback on others' contributions
  • Share your expertise in reviews
  • Suggest improvements to the contribution process

Project Structure

docs/
├── articles/           # Main content sections
│   ├── how-to/        # Step-by-step guides
│   ├── case-studies/  # Real-world examples
│   ├── best-practices/# Expert recommendations
│   ├── code-snippets/ # Code examples
│   └── systems/       # System information
├── about.md           # About EPICURE
├── contributing.md    # This file
└── index.md          # Homepage
mkdocs.yml             # MkDocs configuration
requirements.txt       # Python dependencies

License

By contributing to this documentation, you agree that your contributions will be licensed under the project's license.

Thank You

Thank you for contributing to the EPICURE Knowledge Base! Your expertise helps the entire HPC community make better use of EuroHPC resources.