Masterarbeit/QuellCode/CentronERP/docs/getting-started/documentation-rules.md

Documentation Organization and Maintenance

This guide explains how the documentation in the c-entron.NET project is organized and what steps to follow when adding new documentation files or directories.

Documentation Structure

The project documentation uses a hierarchical directory structure to organize content by topic and purpose:

docs/
├── .order                   # Controls documentation ordering in some documentation viewers
├── README.md                # Main navigation and documentation entry point
├── getting-started/         # Beginner guides and introductory material
├── guides/                  # Step-by-step instruction guides
│   ├── development/         # Guides for development tasks
│   ├── database/            # Database-related guides
│   ├── ui/                  # UI development guides
│   └── services/            # Web services guides
├── reference/               # Reference documentation
│   ├── architecture/        # Architecture specifications
│   ├── database/            # Database reference documentation
│   └── security/            # Security documentation
└── operations/              # Operational procedures and guides

Directory Organization Rules

1. Use kebab-case for all documentation file and directory names (lowercase with hyphens)
2. Organize documentation into logical sections based on their purpose and audience
3. Keep documentation files focused on a single topic or task
4. Group related documentation files in appropriate subdirectories

Adding New Documentation

Creating a New Documentation File

When adding a new documentation file, follow these steps:

1. Choose the right location within the existing structure
2. Name the file appropriately using kebab-case (e.g., how-to-configure-settings.md)
3. Create the file with appropriate content, using Markdown format
4. Update the README.md navigation file:
   • Open docs/README.md in your preferred editor
   • Find the appropriate section corresponding to the directory where you added the file
   • Add a new entry with a link to your documentation file following the existing pattern
   • This step is mandatory to ensure discoverability of your documentation
5. Update the Solution File:
   • Open Centron.sln in your preferred editor
   • Find the appropriate solution folder section for the directory where you added the file
   • Add a reference to your new file in the ProjectSection(SolutionItems)

Example of adding a file reference to the solution:

Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "getting-started", "getting-started", "{01F71AAA-B574-490A-A241-E905C4E4F358}"
	ProjectSection(SolutionItems) = preProject
		docs\getting-started\general-structure.md = docs\getting-started\general-structure.md
		docs\getting-started\landing-page.md = docs\getting-started\landing-page.md
		docs\getting-started\your-new-file.md = docs\getting-started\your-new-file.md
	EndProjectSection
EndProject

Creating a New Documentation Directory

When adding a new documentation directory, follow these steps:

1. Create the physical directory in the appropriate location
2. Create any initial documentation files within the directory
3. Update the Solution File:
   • Create a new solution folder entry for your directory
   • Add references to any files in the directory
   • Set up the proper nesting relationship in the NestedProjects section

Step 1: Add Solution Folder Entry

Add a new solution folder entry before the EndGlobal section:

Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "your-new-folder", "your-new-folder", "{GENERATE-NEW-GUID}"
	ProjectSection(SolutionItems) = preProject
		docs\path\to\your-new-folder\file1.md = docs\path\to\your-new-folder\file1.md
	EndProjectSection
EndProject

Note: Generate a new GUID for each new solution folder. You can use tools like Visual Studio's GUID generator or online GUID generators.

Step 2: Define the Nesting Relationship

In the GlobalSection(NestedProjects) section, add an entry that defines where your new folder belongs in the hierarchy:

{GUID-OF-NEW-FOLDER} = {GUID-OF-PARENT-FOLDER}

Example:

{A1B2C3D4-E5F6-1234-5678-ABCDEF123456} = {2F71ED3A-FF09-4148-BEBA-FE06257EFCE4}

Documentation File Format

1. Use UTF-8 with BOM encoding for all documentation files
2. Start with a # heading that clearly describes the content
3. Use proper Markdown formatting for headings, lists, code blocks, etc.
4. Include links to related documentation when appropriate
5. For internal links, use relative paths to other documentation files

Example: Adding a New Guide

Let's say you want to add a new guide for configuring database connections:

1. Determine the proper location: docs/guides/database/configure-database-connection.md
2. Create the file with appropriate content
3. Update Centron.sln:
   • Find the "database" solution folder under "guides" (GUID: 6DB9540C-9A72-4494-81C3-254BC21214BF)
   • Add your file to its ProjectSection
   • Ensure the path is correct relative to the solution file

Updating Existing Documentation

When updating existing documentation:

1. Maintain the same file encoding (UTF-8 with BOM)
2. Follow the established formatting patterns
3. Check and update any internal references if needed
4. The solution file does not need to be updated if only modifying an existing file

Best Practices

1. Keep documentation up-to-date when the code changes
2. Use clear, concise language that is easy for readers to understand
3. Include examples where appropriate to illustrate concepts
4. Use screenshots for UI-related documentation
5. Link to external resources when they provide valuable additional information

Following these guidelines will help maintain a well-organized, easily navigable documentation structure that enhances developer productivity and understanding of the c-entron.NET project.