Design Documents for Distributed Companies

How do you hash out architecture and design at a remote only company? Slack chats and phone calls are a slow way to communicate with an entire team. And miscommunication with people 1000s of miles away can cost you the time and money you were hoping to save by working remotely. 

The Design Document workflow

Some companies have a design document centric workflow. At the beginning of a project instead of writing Jira tickets or tasking out stories, an engineer will spend some time writing a 3-10 page document which describe the plan of attack for the project. This doc will include assumptions, design decisions and constraints, as well as a summary of the changes to be made. The document is not an exhaustive specification, but can include proposed interface or library changes. Then the team will have a review session to read and ask questions about the design. Next after some revisions, and possibly a follow up session, development will begin. 

Google Docs or any other shared document tool is sufficient to support the document review process. If you want to make the process truly asynchronous you could rely only on document comments and skip the meeting all together. 

Typically, a design document should be required both embarking on any significant project or feature addition. Adding a new button to a web form would not need a document, but building a new web service or adding a major feature would. 

When I worked in a distributed consulting company we used this workflow for proposals and Level of Effort estimates. But software design was usually handled by discussion and whiteboarding followed by implementation with half-hearted documentation occurring at the end of the project. A design document process would have helped share design between the east and west coasts keeping more of our projects on the same page. 

Leave a Reply

Your email address will not be published. Required fields are marked *