Taro Logo

When do I make my design doc public?

Profile picture
Senior Software Engineer at Taro Community7 months ago

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?



  • 2
    Profile picture
    Tech Lead/Manager at Meta, Pinterest, Kosei
    7 months ago

    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.

  • 5
    Profile picture
    Software Engineer @ Taro, Pinterest
    7 months ago

    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.