Text guides

Software projects

Describe behavior, reproduce problems and make handoffs easier to check. Use the project's real instructions and keep credentials out of examples.

12 practical tasks. Each guide includes a sample request and a way to check the answer.

Write a bug report someone else can reproduceA reproducible bug report lets a reader trigger the same problem without asking you anything. List the environment, number the steps from a clean starting point, state what you expected and what happened, and attach the smallest evidence that shows the difference.
Write a feature request around a user problemDescribe who needs the change, the task they are trying to finish and the obstacle in their current workflow. Explain any workaround and the outcome they need. Then add your proposed solution, distinguishing actual constraints from details that could be solved in another way.
Derive test cases from a feature requirementBreak a requirement into one behavior per test case, each with a setup, an action, an expected result and a way to record evidence. Then add the boundaries and failure paths the requirement implies but does not state, before anyone approves the build.
Write release notes from confirmed changesStart with changes confirmed in the released version. Explain what users need to know: new behavior, fixes, relevant compatibility or security updates, and any action required. Include limits and affected platforms. Keep internal implementation detail only where it helps readers understand an impact.
Check a README for missing setup informationRead the README as someone who has never seen the project and wants a working example. Record each prerequisite, setup step and expected output, then note where a newcomer would get stuck, such as an unexplained command, a missing tool or a step that needs a credential.
Ask the missing questions on an incomplete bug reportAn incomplete bug report needs a few pointed questions, not a long form. List what the reporter already told you, identify the details you still need to reproduce the problem, and write one short question for each, with a reason.
Compare technical options against project constraintsList the project's constraints first, then judge each option against them one at a time. For every option, record the requirement it supports, what it costs, what evidence you have and what you still don't know. A note like this can be reviewed after the decision.
Prepare questions before integrating an APIBefore writing integration code, turn what you need from the API into questions and answer each from the current official documentation. Record the source beside every answer. Anything the documentation does not state becomes an open question with a small test.
Hand off a software project with known issues visibleA good handoff tells the next maintainer what works, how to run it and what is broken. List each known issue with a symptom someone can reproduce, a workaround if one exists and a named owner. Leave out general warnings that give them nothing to act on.
Write an acceptance test script for a business userAn acceptance script walks a business user through a real task, from a defined starting state to an expected result. Write each step in the words the user already uses, say what they should see afterward and leave space to record what actually happened.
Turn incident notes into a factual timelinePut each event in order with its timestamp and time zone, then record what was observed or done and where the evidence is. Keep explanations for later. A timeline that mixes facts with theories about cause is hard to trust and harder to correct.
Prepare review questions for a software changeStart from what the change alters in behavior, then trace which paths and stored data touch it. For each affected path, name how it could fail, how to check it and what recovery looks like. That gives a reviewer concrete things to examine.

Related topics