My previous blog post focused on the side effects of ‘over documentation’s’. I identified reasons why so many projects are struggling with documentation and listed a few solutions how to prevent it. One of the solutions was that you should keep your documentation close to the source code.
Documentation as a service
As I previously wrote, documentation is valid only when it’s up-to-date. A development team will create and maintain most documentation, so it must be as developer friendly as possible.
Developers are craftsmen who make products with the help of programming code. If a developer can code and create or maintain documentation simultaneously, there is a good chance the documentation stays up-to-date. Next, we will see two examples of this ‘keep documentation close to the source code’ approach.
Dynamic style guide
A style guide is a comprehensive document that keeps track of all the common user interface elements for a project track of all the common elements for a project, from branding rules to the amount of bevelling for call-to-action buttons. On a more holistic level, a style guide defines the design philosophy for a company. A traditional way to create a style guide is in a separate pdf-document, which usually ends up being out-of-date.
A better alternative is to create a dynamic style guide. A Finnish software and consulting company SC5 Online has created a useful open source tool for this. The tool generates a style guide catalogue, where user interface elements and styles are grouped and visible to everybody. When a developer edits a style, changes will be updated to the product’s UI and the style guide catalogue.
The dynamic style guide eliminates the need for static style guide documents. Business people can review styles online and developers can make quick changes anytime. Ultimately, this approach simplifies and standardizes the whole UI design.
API documentation
Software components need APIs (application programming Interface) to communicate with other components. Some believe that we will soon have an ‘API economy’, where organisations can positively affect their profitability via APIs. Anyhow, API documentation is a crucial part of the quality of software projects; the traditional way to have API documentation is in excel-documents, where data models, operations, URIs etc. are defined.
Swagger is a good example of a modern documentation tool. Swagger is a specification format that describes an API in a common language everyone can understand. Swagger packs everything about the API in a single and dynamic file which is easy to use.
The benefits of Swagger are clear. With Swagger, it is possible to design and document APIs simultaneously, thus keeping the blueprint and documentation in sync. Developers and non-developers can both have input to the API design because of the user-friendly UI. Swagger is readable by both human and machine, which gives a possibility to share documentation externally and allows powerful integration. Swagger contributes to API design in the same way that SC5 Style Guide contributes to style design – simplifying and standardising it.
Minimum Viable Documentation
Although all projects are unique, there are general documentation patterns that can be used. While reading my ‘Minimum Viable Documentation’ list, think how you could keep this documentation close to the source code in your project:
- How to get started – a tutorial for how a new developer sets up a development environment
- Design guidelines – see above
- API documentation – see above
- Definition of Done – define teams’ responsibilities
- Coding conventions – a set of guidelines and standards for programming languages
- Licenses – make visible which open source and other licences are used in the product
- High-level architecture descriptions – illustrates software architecture from different angles, for example, infrastructure, application, and integration. Favour pictures
- Maintenance process – if you can document a maintenance process, you can most probably also script it
- Principles for general tech. features – such as version control, authorisation, authentication, logging, validations, localisations etc.
- The most complicated business rules – such as complex algorithms, mathematical formulas and extensive searches
Fossil of the Project
‘It’s code which always wins; not comments or documentation’ is a common phrase. Still, many projects create way too high standards for documentation, although working software should be valued over comprehensive documentation.
The good news is that the new generation of software professionals are more enlightened. For these people, customer satisfaction, service design, JavaScript frameworks, team morale and fast feedback loops are more important issues. Documentation is just out of fashion – for a reason.
Graphic Design
Ville Takala
References
https://www.uxpin.com/studio/blog/great-ui-design-requires-smart-style-guides/
http://styleguide.sc5.io/
https://www.alleyinteractive.com/news/advanced-techniques-for-the-sc5-styleguide-generator/
http://searchmicroservices.techtarget.com/definition/API-economy-application-programming-interface-economy
https://swagger.io/
https://blog.readme.io/what-is-swagger-and-why-it-matters/
http://agilemanifesto.org/
