In this post, I would like to talk about software development guidelines.
I will try to explain what they are and what distinguishes them from guides or tutorials. Eventually, I will try to explain the qualities of a good software development guideline.
Software development guidelines
Let’s define what a software development guideline is:
A software development guideline is a piece of information intended to advise developers. In particular, it offers advise on how various aspects of the software development process should be done or what they should be. Furthermore, the advise it offers is non-specific and focuses on rules and principles.
For example, a guideline may give advise on:
- how to organize developer teams
- how to conduct testing
- which technology stack to use
- what design patterns to follow or to avoid
Content of a Guideline
The content of a guideline is always specific to the team(s), software and the technology organization. It typically reflects:
- strategic goals and priories in the technology organization
- the needs and the maturity of the development teams
- the software development culture
- architectural and technology choices
- specifics of the software being developed
- the size of the technology organization
Guideline vs Guide vs Tutorial
Very often, we tend to confuse guides and tutorials with guidelines. For this reason, I would like to clarify the differences between them.
As already mentioned, guidelines are generic and focus on non-specific rules or principles.
In contrast, guides are specific, provide information and in depth explanations. Guides typically aim at showing someone around a particular aspect of the software development process.
For example, a guideline could include a rule that every project should use a git repository. Additionally, it could also suggest that every git repository should include a README file. Perhaps, it may even suggest to use a specific README template.
A guide on the other side, would show developers around the specific git hosting platform the organization is using.
Furthermore, the README files of each repository, would guide developers in the specifics of the code-base of each project.
A tutorial on the other hand, focuses on educating its audience in a very specific subject and offers step-by-step instructions.
For example, a tutorial could explain how to use the README template. It would offers step-by-step instructions on how to customize it and edit it with a code editor.
Qualities of a good guideline
A good guideline, should have the following qualities:
Is Clear
- The audience can easily understand the content
- Uses simple language
- Explains terms and abbreviations
- Gives a rationale
- Conforms to visual design standards for code, diagrams etc.
Gives Direction
- Defines rules and principles to follow
- Offers advice
- Sets goals and helps the audience to achieve them
- Shows the relationship with the architecture, principles, decisions and goals
- Gives hints for further reading
- References particular (more specific) guides that describe how to apply it
- Explains which topics it relates to
Sets Boundaries
- Defines what is in-scope and out-of-scope
- Explains what the audience MUST, SHOULD, MAY do and NOT to do
- Gives patterns to follow and anti-patterns to avoid
Is Relevant
- State explicitly whom it applies to
- Sets the context
- Defines the circumstances and conditions that apply
Is Lean
- Includes only parts that bring value to the audience
- Focuses on the important
Is Valid
- Shows explicitly the validity status [DRAFT, FINAL, DEPRECATED] of its content
Is Up-To-Date
- Includes information that is up-to-date
- Does not contain obsolete or out-dated information
- Includes a version and the contents is dated.
Can be Trusted
- Shows the authority that issues the guideline
- Explains how to address and resolve conflicts within the guideline and with other guidelines
Examples of Guidelines
Bellow, you can find links with guideline from some well known companies. They may serve as examples to follow or to inspire you when you write your own guidelines.
Zalando: Developing Restful APIs [3]
Atlassian: REST API design guidelines version 1 [4]
Baeldung: Guidelines for the code in articles [5]
Google: Quality guidelines for Android apps [6]
