Developers and clients think differently

A client writes: the header is wrong on my phone. A developer reads that and thinks: viewport, breakpoint, which phone, which browser, is there a screenshot. Both are talking about the same piece of work. Neither is speaking the other's language, and neither should have to.

Most tools handle this by pretending it is not so. Either the client is put in the developers' tool, where every word written about the work — the branch name, the failing test, "rebased, please re-check" — sits in front of them; or the developers are pulled out of their tool into something with coloured cards, and the work is typed twice, once where the client can see it and once where the branch lives. The first is noise for the client. The second is a second job for the developer, and it is the job that quietly stops being done.

Two rooms, one piece of work

The shape that works is two rooms with a door between them. The client has a room of their own: the task, in their words, with the notes they write and the answers they get. The developers have the repository: the issue, the branch, the pull request, and everything they say to one another while the fix takes shape. The task and the issue are the same piece of work, so they stay in step — the title, the status, who it is with. The door is what makes it bearable: nothing goes through it unless somebody carries it.

That last sentence is the whole design, and it is worth being exact about, because the obvious alternative — send everything both ways — is what most integrations do, and it is why most integrations are switched off within a month.

What crosses on its own, and what does not

Start with the client's side. What a client writes on a task always reaches the developer. It is the header, on my phone, when I turn it sideways is precisely what the developer needs, and there is no version of that sentence that is noise. So a client's note lands under the issue, with the client's name on it, and the developer reads it where they already are.

Now the developer's side. What a developer writes under an issue does not come back on its own. Reproduced on the latest phone release, looks like the flex container, rebased onto main, a pasted stack trace — the client cannot use any of it, and worse, a client reads every note on their task. Ask a client to sit through a week of that and they stop reading notes altogether, which is the one thing the room was for. So the developers' conversation stays in the repository. The task shows that it is happening — three in Gitea — so nobody wonders whether anyone is on it, and nobody has to read it to find out.

When a developer does have something to say to the client, they say so. One word at the front of what they write, /share, and that line — only that line — becomes a note on the task in the developer's name. Fixed on staging, please check the header on your phone. The client reads a sentence written for them. The developer never left the repository, and never had to decide whether the whole thread was fit for a client, only whether this one line was.

Status is the other language

Statuses are where the two ways of thinking show most. A repository knows open and closed. A client wants to know whether anyone has started, whether it is stuck, and whether it is waiting on them. Joining the two badly — closed means done, and leave it there — tells the client a paused piece of work is finished, or hides that it is blocked.

So the door carries the meaning, not only the state. A task marked done closes the issue and says why. A task put on hold leaves the issue open, because the work is paused, not over, and closing it would tell the developer to stop caring rather than to stop working. In progress and blocked ride on the issue as labels, so a developer who sets one sees the client's task follow. Every change explains itself on the other side, in the other side's words.

Nothing typed twice

Add it up and the developer does their work in the repository, the client reads and speaks on the task, and the tool does the carrying. Nobody copies a title. Nobody forwards an email with "see below". Nobody writes a Friday status paragraph, because the Monday email already says what moved, and the client can see the rest for themselves. The work itself is still one task with one owner; it simply has two audiences.

The rule underneath is simple enough to say in one line, and it is the one to hold any integration to: the tool should know which words belong to whom, and let nothing cross by accident. The details of how sjTasks does it — the two labels, the door in both directions, what a developer can and cannot change from the repository — are in the guide to Gitea, and the shape of a shop run this way is on the page for development shops.

The question this answers is the one the client asks and the developer dreads: Show me what is happening with my task. When the answer is a sentence written for them rather than a thread written for someone else, they ask it less, and they trust it more.