Write a technical design draft
Turn a feature idea into a design doc that fits how the code works today.
Engineering · Software · When you ask · Updated
Works with
- Slack
SlackHow do you write a technical design document?
To write a technical design document, send Maito the feature idea in Slack. It reads the repository, maps what has to change in data, API and screens, splits the work into phases, flags existing code that gets in the way, and attaches a draft for your team to edit and review.
How it's done today
Design docs miss how the current code really works.
What Maito does
- Read the request and the relevant code
- Draft the approach, changes and risks
Example
@Maito draft a design for adding team-level permissions. Admins should be able to give a team access to a project.
Draft attached: team-permissions-design.pdf (4 pages). Data: 3 new tables: teams, team_members, project_team_roles. API: 6 endpoints, 4 of them new. Screens: team list, team detail, a Teams tab on project settings, and the invite dialog. Phases: 1) one permission check, 2) tables and API, 3) screens. Catch: permissions are checked in 31 places with user.role === 'admin', not through one function. That has to be fixed first, or a team member will be allowed in some places and refused in others. Open questions: • Does the most permissive team role win? • What happens to today's members? • Do API keys inherit team access? From reading the auth and projects code. I can start phase 1 on a branch.
Alex (3:30 PM):
draft a design for adding team-level permissions. Admins should be able to give a team access to a project.
Maito (3:52 PM):
Draft attached: team-permissions-design.pdf (4 pages).
Data: 3 new tables: teams, team_members, project_team_roles.
API: 6 endpoints, 4 of them new.
Screens: team list, team detail, a Teams tab on project settings, and the invite dialog.
Phases: 1) one permission check, 2) tables and API, 3) screens.
Catch: permissions are checked in 31 places with user.role === 'admin', not through one function. That has to be fixed first, or a team member will be allowed in some places and refused in others.
Open questions:
• Does the most permissive team role win?
• What happens to today's members?
• Do API keys inherit team access?
From reading the auth and projects code. I can start phase 1 on a branch.
How to set it up
- Set up
Nothing to set up. Ask in Slack or by email whenever you need it.
What it won't do
A design draft is a starting point. Trade-offs, cost and timing decisions are made by your team, not by Maito.
Questions
Yes. It reads the repository first, so the plan refers to real tables, endpoints and files instead of a generic template.
A document attached in Slack, such as a PDF. You can ask for a different layout.
Yes. If the idea leaves out a decision, it asks in the thread and continues when you reply.
