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 framework for 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.
  • Governance and Compliance Controls: A collection of key controls and processes designed to ensure adherence to governance standards and compliance with both internal policies and external regulations.

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.

Governance and Compliance Controls shield

  • Definition: A collection of key controls and processes designed to ensure adherence to governance standards and compliance with both internal policies and external regulations.
  • Purpose: To track compliance with the mandatory sections of the handbook, including policies, rules, and standards. This section ensures that all critical governance measures are documented and enforced, providing oversight on adherence to the core practices that uphold the quality and security of our software development process.
  • Lifecycle: Controls are reviewed quarterly or following significant changes in regulations, technology, or business needs to ensure they remain effective and relevant.
  • Compliance: Mandatory for all teams. Any deviation or non-compliance may result in audits, corrective actions, or further review, ensuring alignment with organizational standards and legal requirements.
  • Icon: shield (shield). It symbolizes protection and security, representing the safeguarding of our software engineering practices through strong governance and compliance.
  • Example: A control might track instances where code merges bypass branch protection, ensuring that changes still follow the correct peer review process to maintain code integrity.