Requirement engineering is an entire subfield of software engineering, one that relies heavily on your communication skills: writing requirements is about defining your customers' fundamental problems, goals, and needs, that will later be answered by a software system - a mobile app, a website, an application programming interface... a tech product.
A requirement specifies the desired behavior of a product, which can either be functional (a task, what the product does) or non-functional (a quality/constraint, how the product does what it does).
A requirement is always written from the point of view of a variety of stakeholders, which is why a certain quality is needed to make requirements easily understandable. This way, a stakeholder can agree on a set of requirements, as to avoid any unnecessary change down the road - which greatly increases the probability of a project's success since changes are expensive.
You elicitate requirements by talking with your users. It looks simple, but finding relevant users for your target segment is hard. It's a maieutic process that takes skills.
All requirements are documented in a central repository. In 200WaD's case, it's a public Trello board, but in big companies, it's not unusual to use dedicated tools. Having a persistent common reference is incredibly important to ensure the project's transparency and knowledge transfer.
Requirements are put down on paper following a SMAR methodology: Simple - complete, unambiguous, understandable, atomic ; Measurable - traceable and verifiable ; Achievable ; Realistic - necessary and consistent. Different formats are possible: formal languages (programming language) and semi-formal languages (UML diagram...), but as indie makers we should always opt for natural languages (English).
Natural languages are easily comprehensible for everyone, which comes at the cost of under-specification, fewer details can be described efficiently. This is why when you read Makerlog tasks, it's really hard to understand what those mean and how they fit in the overall product.
To solve this issue, we can find inspiration in a requirement engineering methodology known as GORE - Goal-Oriented Requirement Engineering. In this framework, requirements are directly linked to the overall goals of a software system - why it exists. Goals are decomposed into sub-goals, which are then tied to user stories.
A user story is a well-known term in Agile project management describing a product's atomic use case in a measurable fashion. User stories are high-level requirements in terms of abstraction. In my opinion, those are the molecular statements you want to log in your public accountability system: a card in Trello, or a task in Makerlog.
User stories can then be decomposed in more technical tasks or constraints - checklists in Trello or individual commits in Git.
Your public requirements must be written in a way your readers can easily understand, otherwise, they are useless to them:
- High-level requirements in the form of user stories
- Mention the project and the corresponding sub-goal: "Landing page redesign", "Editor feature", etc.
- Always write with clarity
- Diversify your tone: make it interesting and inspiring to read, not always formal.
- Use illustrations: emojis, pictures, anything helps really.
- Follow-up: don't forget to explain and celebrate your product milestones next to your requirements. Makerlog has a dedicated feature exactly for that!
- Do not go too deep: low-level requirements belong to git commit messages or roadmap sub-lists - ie. "wrote function X in class Y"
- Do not be too broad: you need to be specific to be understood and to invite interactions.
Programming software is a lot like writing when you start thinking about your end-users. Start improving today!