Documentation Concepts

Documentation Concepts

Consistency in terminology and structure enhances clarity and usability of the documentation.

Naming Conventions:

1. Creating Records:

   • When the process involves creating a record, use “create” followed by the record type (e.g., “create record”, “create user”).
   • Avoid using terms like “add”; consistency in vocabulary is crucial.

2. Editing Records:

   • For editing processes, use “edit” followed by the record type (e.g., “edit record”, “edit user”).
   • Avoid using terms like “change”, “modify”, or “adapt”.

3. Adding Related Records:

   • If the process involves adding a record directly related to another record (e.g., adding a role to a group), use “adding” instead of “creating”.
   • This distinction emphasizes the relationship between records.

4. Implication of Existing Records:

   • Ensure clarity that adding a record implies the existence of related records.
   • For example, adding a role to a user implies that the user already exists.

Documentation Structure:

• Title Format:
  • Begin with “How to” followed by the specific action or task (e.g., “How to Add Public or National Holidays to a Schedule”).
• Introduction:
  • Provide an overview of the importance and relevance of the task.
• Instructions Section:
  • Consistently named as “Instructions”.
  • Present step-by-step guidance for performing the task.
• File Naming Convention:
  • Use “how-to” as the folder name.
  • Followed by:
    • “create-xxxxx” for creating records.
    • “edit-xxxx” for editing records.
    • “add-xxx” for adding related records/actions.

Example Structure:

# How to Add Public or National Holidays to a Schedule

In Brinkee, the addition of holidays is essential for accurate calculation of time off requests. By incorporating holidays into the platform, users can conveniently plan their time off while ensuring that schedules and workload management remain efficient. This guide provides step-by-step instructions for IT administrators to add holidays to the Brinkee platform.

### Instructions:
1. Step 1: [Instruction details...]
2. Step 2: [Instruction details...]
3. Step 3: [Instruction details...]
   ...