For large-scale Drupal projects, one of the tools we use at the requirements-gathering stage is a build spec document. Previously, we used the one from palantir.net’s blog post. But with the arrival of Drupal 8, having Media in core, and the Paragraphs module, we needed an updated version.

Drupal 8 Build Spec 1.0

Although this is a technical document, mainly for use by developers, producing it at an early stage helps to inform the whole project by raising questions about how the system will work. For example:

• “What page templates do we need?” – By listing likely content types, as well as views, we have an idea of what templates will need to be designed, and what fields are likely to appear.
• “Is this vocabulary really a content type?” – If you find that a vocabulary is being given fields and is likely to have its own templates, you might consider making it a content type instead.
• “Should the banner image in news/events items be mandatory?” – If clients don’t have appropriate images, will they be able to use default images, or will the design need to accommodate items without images?
• “Can programmes belong to more than one theme?” – If the design uses colour-coding, what happens if an item can have more than one theme attached (or none)? Can the design accommodate this?
• “How will the site be structured and what should URLs look like?” – In addition to sitemaps, there’s a philosophical question of how to structure paths and where each item of content should live. By nesting destination pages under a theme, you risk limiting the flexibility of these pages and creating unwieldy URLs. Defining simple paths based on content type is often cleaner and more flexible.
• “Should this intro text include HTML?” – The intro text in a design may be plain paragraph text, but will users want to use simple formatting?
• “What image styles do we require?” – How should the system scale and crop images, and will content editors need to find images in specific dimensions?

This is a sample of the types of question that are prompted by filling in the spreadsheet, and all require input from clients, copywriters, designers, and front-end and back-end developers. For this reason, it’s useful to complete the spreadsheet early in the process. Whilst the document itself is technical and geared towards Drupal developers, it can be shared with all parties, alongside other requirements documentation such as a more traditional functional specification document (with MoSCoW prioritisation) or user stories.