6 ms·
You have to learn to write, and get comfortable doing it. When I was the (de-facto and later de-jure) architect, I was too reliant on in-person synchronous dis
by squeed 6y ago
You have to learn to write, and get comfortable doing it.
When I was the (de-facto and later de-jure) architect, I was too reliant on in-person synchronous discussions. I neglected my e-mail and design-document skills.
The result: everything had to be synchronous. Chat was a wasteland. Decisions where one just had to Sit Down and Think wasted multiple people's time. I realized I was subconsciously avoiding writing long documents.
Part of the problem was - no kidding - I needed a new glasses prescription. But mostly I just needed to get used to the act of sitting down, drafting, and writing a design document. I also needed to encourage the team to have a bit of discipline and design before coding.
Later, as I transitioned out of a "move-fast-and-break-things" place to a large open-source project, my learned avoidance of writing definitely hurt me. I was not practiced at asynchronous design and development.
- awithrow 6y ago> Part of the problem was - no kidding - I needed a new glasses prescription. Huh, what did the glasses have to do with it? Old prescription making it hard to read text for long periods of time?
- artsyca 6y agoYes I've suffered the same - farsightedness making it hard to focus literally and a slight astigmatism where one eye focuses a little better than the other combine to increase fatigue and make prolonged writing very difficult With glasses my whole mind relaxes and I can settle right into the zone
- squeed 6y agoYeah, same here. It turns out I could focus, but it took a lot of brain power to actually and understand text. Getting new glasses lowered the cognitive load.
- stronglikedan 6y agoYes, and in my case, it's still hard to read text off a backlit screen, even with the right prescription. I have to use e-ink or paper if I'm going to be reading for a while.
- mcv 6y agoI fear this is great advice. I too avoid writing documents. Or even reading them. I want to have my hands in the code, but it's increasingly clear to me that I need to write more stuff down.
- xinau 6y agoI had/have the same problem, what helped me a lot was to write down what I've learned (roughly bi-weekly). Another booster was to stick to the same document structure for example NABC for proposals and ideas. NABC: https://nielschrist.wordpress.com/2012/07/13/the-nabc-method-standford-research-institute-sri/ https://nielschrist.wordpress.com/2012/07/13/the-nabc-method...
- deleted 6y ago[deleted]
- gonzo41 6y agoI don't fear writing documents, but i do work with a lot of people who do fear reading! I've found a really good trick is to highlight key figures or a few standout grabs in the early paragraphs of the text and then to have more substantial higlights towards the meaty parts of the document. Essentially it's like having the bullet points and full document in one. It;s resulted in a lot of people getting interested up top and being tricked into reading down the bottom. Give it a try sometime.
- squeed 6y agoFor sure. Part of being a successful writer is communicating in a way that is most effective for your audience. Rarely is a wall-of-text the right answer. Bullet points, flow diagrams, and examples are all helpful techniques when writing for engineers.
- larrywright 6y agoWriting would be valuable to me even if nobody else ever read the documents. I find that writing helps me think through a problem much better, and in the end I have a better solution.
- dotdi 6y agoThanks, I feel this is great advice! I used to insist on writing down the things that were just floating around in the heads of the more experienced team members, and it went really well for a time. I was part of the effort that pushed for better infrastructure for documentation, and we did get it in the end. But, alas, this stalled and so did the excitement about having documents.
- shadowfox 6y agoThis is a great advice. Do you know of any publicly accessible design documents that you would consider good (to serve as An example)?
- tootie 6y agoI've been an architect for a long time and have written a lot of tech documents and can say with confidence that no one ever reads them.
- yonixw 6y agoSame. I Always talk and discuss with diagrams, the more colourful the better (like AWS components).
- manojlds 6y agoDid you properly read the parent comment you are replying to?
- rammy1234 6y agoIt's ok if he didn't, comment was positive way to say what he does instead of saying that was crap.
- cbanek 6y agoAgree. Usually when I write a document, it's usually centered around a few "hero" diagrams, with most of the text explaining it. Afterward it's always the pictures that are the most useful for me, but maybe we're just visual learners!
- gtf21 6y agoI frequently write architectural documents and as a team we find it a very useful way to collaborate. We structure them as RFCs (meant literally, in that the document is designed to solicit comments, and so are often proposals). I've never had an engagement problem with them.
- mjayhn 6y agoI'm on the ops-architect end and I read design docs and usually steal all of the plantuml and everything else I can find as nobody ever (aside from the developer of the feature) can help me track down or troubleshoot problems and I find most developers to be very disorganized (I was too until recently and it's still something I work on daily). So the documentation is appreciated. I also write a lot of ops-focused docs and tools, like stuff to lower MTTR and just generally help my ops teams relax and be lost less often when alerts come in. An ops person should never get an alert at 2am and be completely lost, no playbooks or guidance or anything because a lack of implementation documentation, I've been there, it sucks and will make you regret your employment. I don't think most of that gets read either. But I still do it. I just assume most people are siloed in their own projects and barely have time to get those done so reading ancillary stuff is on the backburner. But if some emergency ever comes up at least it's there and if I'm on a mountain I got everything out of my head so you won't need me to walk you through how something works over the phone. With that said, I face immense frustration when I go into a microservice repo that is scaffolded hoping that some golang developer updated the readme to actually be relevant and not the scaffold template and 99% of the time for internal stuff it's never, ever touched. Please do some documentation for Ops/new-devs, etc. That extra 30-2 hours of work will save half a day of some new person trying to launch your service in KIND or whatever, now compound that over every new person/outage/time you've had to explain something that you didn't document. The readme.MDs in every single one of your microservices should not be a base template with zero touching. It's not hard work to give someone who has never touched it some breadcrumbs on what your service does. Half the time I go in there when something is already broken and the stress is high hoping for simple stuff to get me going, even just some basic UML of what apis its talking to, what kubernetes resources it needs, what RBAC permissions, etc. Think of yourself having never touched the service and leave some pointers/best-practices for someone who has never touched it or troubleshot it (like your ops people when you throw it over the fence for deployment). Having to figure out your microservice architecture via container logs when SHTTF is miserable.
- logfromblammo 6y agoLearning how to make concise, effective infographics is a part of learning technical writing. A picture may not always be worth exactly 1000 words, but images with high cognitive density are usually worth putting into your document.
- jugg1es 6y agoI can't stress how important it is to get good at writing design documents and producing effective diagrams. If you do not produce these artifacts, it is very difficult for your developers to do what you want them to do. You end up spend way more time re-explaining yourself than you would have spent documenting.
- finder83 6y agoDo you have any advice or tools for diagrams? That's one area I struggle with, and usually have to pull in our designer.
- qznc 6y agoPlantUML if you want to maintain the diagram in version control. yEd for interactive use because of its auto-layout function. Not unintuitive to use though. It takes some effort to learn. Enterprise Architect if your company pays the money and you really need its features (e.g. SysML diagrams). Whatever is close by. For example, we use Confluence for our wikis. It has a Gliffy plugin, so I often use that for embedding diagrams. I've seen photos of whiteboards, drawings in MS Paint, and other stuff. The tool rarely matters. What matters more is the content. A few tips for that: Have clear meaning what a box means and what an arrow means. Don't make it inconsistent like "this box is a server, this box is a software component, and this box a message". If you need multiple types, then draw them differently (colors, rounded corners, dotted, etc). One statement, one diagram. Don't make multiple statements in one diagram like "Here you see we send do more messages then necessary and you also see the undesirable coupling between Foo and Bar". Ok, there is also value in overview diagrams to show "everything" but those are for live use in discussions and not for documentation which should be understandable on its own.
- finder83 6y agoThanks!
- jugg1es 6y agodraw.io (which is now app.diagrams.net) is all I've ever needed. I got my company to buy the Confluence plugin for it too. It's free to use by itself.
- gregmac 6y ago> avoiding writing long documents. Just to pick on this bit: You should still avoid writing "long documents". Spend the time to make your documentation as concise as possible. And make no mistake, making it shorter is much more effort and takes longer: "I would have written a shorter letter, but I did not have the time." -Blaise Pascal, 1656 Nobody reads big, long wall-of-text documents. Break things into smaller sections, and be sure each section has a clear audience in mind (developer implementing initially? support debugging a production problem? QA building test cases? tech writer making user-facing docs? PM?). Good rule to retroactively build up your docs: When someone asks a question, answer it with a link to the docs. Sometimes this means writing new documentation.