When do I make my design doc public?
At my startup, we use Confluence to host various documentation. I'm working on a design document draft, and I have it saved within the org's Architecture and Engineering Space (basically a folder). I have some misgivings about placing it there since I've been regularly updating it, and it notifies everyone within that group whenever I do. I'm mainly putting it there for visibility, but some of the writing is half-baked. Since it's a small company, no one really cares, but I think this might reflect poorly on me if it were a bigger company. How does Big Tech generally handle this design doc process from first to final draft? Do engineers generally just keep it within their personal Space until it's ready for review?
![Senior Software Engineer [E5] at Meta company logo](/_next/image/?url=https%3A%2F%2Ffirebasestorage.googleapis.com%2Fv0%2Fb%2Ftech-career-growth.appspot.com%2Fo%2Fcompany_logos%252Fmeta.jpeg%3Falt%3Dmedia%26token%3Da7a5bcc0-e178-4b5b-b71e-09bf6c6aefae&w=48&q=75){kind=small}
![Entry-Level Software Engineer [L3] at Google company logo](/_next/image/?url=https%3A%2F%2Ffirebasestorage.googleapis.com%2Fv0%2Fb%2Ftech-career-growth.appspot.com%2Fo%2Fcompany_logos%252Fgoogle.jpeg%3Falt%3Dmedia%26token%3D780356ef-3efc-4728-9eb4-d909b75bb4a6&w=48&q=75){kind=small}
Discussion
(2 comments)- 5a year agoSoftware Engineer @ Taro, Pinterest
Everyone is probably too busy with their own work to read it. Make sure to mark the doc as being in process just in case someone does read it. But, no one is going to judge the doc prematurely especially if you have the doc status set to being a draft.
I agree with Rahul about finding alignment with individual stakeholders first. You'll avoid going down the wrong path, and you will partially have their sign-on by the time you publicize the doc.
- 2a year agoTech Lead/Manager at Meta, Pinterest, Kosei
For a large enough project, you should socialize the ideas behind the design doc in individual conversations as you formulate it. If your first external feedback about the design is when you publish, it's already too late.
That said, share the design document as soon as you feel the feedback will be helpful. That typically means the doc is stable enough that the feedback you receive is actionable, but not so stable that it's difficult for you to change.
