Introduction

When organizations add more people (scale up) it quickly becomes impossible to have everyone sitting in the same room to discuss and agree on matters and share the same approach to doing business.

This is my version of a Software Engineering Quality Handbook where it’s easy to get an overview of how an organization can use a well-structured hierarchy for describing how work is done which is crucial for ensuring clarity, consistency, and compliance within a team. The handbook is built up with 5 layers:

  • Policies: Broad statements that define the organization’s principles and compliance expectations.
  • Rules: Strict directives that must be followed to ensure specific outcomes in certain situations.
  • Standards: Mandatory technical and operational requirements that ensure consistency and quality.
  • Processes: Detailed, step-by-step instructions that specify how to perform specific tasks.
  • Guidelines: Recommended best practices that guide decision-making but are not mandatory.

Each layer of this structure supports the one above it, providing more detail and specificity. Policies and rules sets the foundation and create alignment within the goals of Software Engineering, while standards, procedures and guidelines provide the specifics on how to achieve those goals effectively.

This structure also facilitates easier updates and management. Policies and standards often require more thorough review and approval processes due to their impact and scope, whereas guidelines and procedures can be more dynamic, allowing for quicker adaptations to new technologies or methodologies..

Policies :scroll:

  • Definition: Broad, high-level statements of principles, goals, and overall expectations of the organization.
  • Purpose: To establish core values, company vision, and overarching compliance standards.
  • Lifecycle: Reviewed annually to ensure alignment with evolving legal, technological, and business conditions.
  • Compliance: Mandatory; non-compliance can result in significant legal and business risks.
  • Icon: :scroll: (scroll). It symbolizes official documents, which aligns well with the formal, foundational nature of policies. It’s often used to represent ancient laws and decrees, making it fitting for the foundational rules and standards within an organization.
  • Example: A policy might state that all software developed must comply with GDPR and other relevant data protection regulations.

Rules :scales:

  • Definition: Explicit, often granular directives that are compulsory and usually narrow in scope.
  • Purpose: To ensure specific outcomes or behaviors in particular scenarios.
  • Lifecycle: Reviewed frequently (e.g., annually) to refine and ensure they address current challenges effectively and are adhered to.
  • Compliance: Strictly mandatory; non-negotiable and must be followed exactly as prescribed.
  • Icon: :scales: (scales). It represents justice, balance, and fairness, aligning with the concept of rules ensuring specific outcomes and behaviors are maintained in a structured and equitable manner within an organization.
  • Example: A rule might state that commit messages must include a ticket number from the issue tracker.

Standards :straight_ruler:

  • Definition: Specific mandatory requirements for how certain policies are to be implemented.
  • Purpose: To ensure consistency and quality across all projects by defining technical and operational criteria that must be met.
  • Lifecycle: Updated biennially or as needed to reflect new industry practices and technological advancements.
  • Compliance: Mandatory; essential for maintaining quality and uniformity in outputs.
  • Icon: :straight_ruler: (ruler). It symbolizes measurement, precision, and consistency, which align closely with the idea of standards setting specific requirements and guidelines to ensure quality and uniformity across projects.
  • Example: A standard might specify that all code must undergo peer review or adhere to a particular coding standard like ISO/IEC 27001 for security.

Processes :tools:

  • Definition: Detailed, step-by-step instructions that must be followed in specific situations.
  • Purpose: To ensure activities are performed consistently and effectively, especially for complex or critical tasks.
  • Lifecycle: Regularly tested and updated, ideally after major project milestones or annually, to adapt to process improvements and feedback.
  • Compliance: Mandatory where specified; critical for ensuring consistency and reliability of specific operations.
  • Icon: :tools: (hammer and wrench). It symbolizes tools and construction, fitting for the concept of processes as they provide detailed, step-by-step instructions necessary to construct or execute specific tasks systematically and efficiently.
  • Example: A process might outline the steps for a release process, including code freezes, testing protocols, and deployment checks.

Guidelines :compass:

  • Definition: Recommended approaches that are not mandatory but are suggested as best practices.
  • Purpose: To guide developers in their decision-making processes by providing options that align with best practices.
  • Lifecycle: Evaluated and possibly revised every two to three years, or more frequently to incorporate innovative techniques and tools.
  • Compliance: Optional; best practice recommendations that are advisable but not required.
  • Icon: :compass: (compass). It symbolizes guidance, direction, and navigation, which aligns well with the purpose of guidelines to provide recommended approaches and best practices that help steer decisions in software development.
  • Example: Guidelines might suggest using certain frameworks or libraries that enhance productivity and maintainability but are not strictly required.