Binding yourself to high level design by details - irrevocably

Little over half a year ago I was present in an unprecedented blunder by a team leader. I saw how the fervor to succeed  made for a design mishap and how the same fervor made for a Mr. Know It All team leader. TL;DR detailed designs are for devs, not VPs or CTOs

How to not design like a galley master and not be shackled like a rowing slave

When one is asked to make the design document of a new development, one must be very very careful how flows are put on paper. These documents are binding and every word or terminology in them can and will haunt one for a long time. In order to try to minimize a possible mess here are some rules of thumb, gathered from my own experience

Detailed documents glide up like migrating birds

High level design documents may and will end up to the higher ranks of the corporate hierarchy. Be vague when describing functional parts. Do not put highly detailed implementation details in a high level design, otherwise once the details are stated and a VP of anything has seen it stated then everything is bounded to it and surround it. Changing that code will be next to impossible for a long time. Document your high level design but keep the fine details of implementation out of it. By all means however address all fine details of requirements.

State your terms of surrender... clearly

Agree on terminology. For example one can break things to fragments or chunks. Use either or. Always remember that although no one is perfect at naming flows, classes, modules or methods things do tend to stick. Using two names for the same thing will make a mess. Choose one term and stick to it.

Be the master of your diagram

Highly detailed UML diagrams are hard to read. Prove your mastery at design by capturing the essence of a flow in as few lines of drawing as possible. Highly detailed diagrams on high level designs make for poor mastery and bind you irrevocably. There is merit in vagueness. It keeps you flexible to architect your code as you like while keeping you inline with your high level design.

Consult your team

In case you are required to perform the fallacy of putting implementation details in a high level design, do consult your team. You do not own the absolute truth. You do not know it all. You are human. Ask for your teams ideas. They are there not only to code a product but to have fun and participate.

Consult the internet

If you made it to team leader and you don't have a steady stream of tech blogs or publications to read on some spare or dedicated time then go and do it. It is inconceivable to not do so at this stage of your career. I am not saying to be like me, coding at home and having a blog. I am saying, stay updated and on top of your game. Not every solution or post may fit you, at least not today, maybe not ever, but ideas and solutions will come easily if you do keep up with tech rather than not.