4 ms·
I'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.
by tootie 7y ago
I'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 7y agoSame. I Always talk and discuss with diagrams, the more colourful the better (like AWS components).
- manojlds 7y agoDid you properly read the parent comment you are replying to?
- rammy1234 7y agoIt's ok if he didn't, comment was positive way to say what he does instead of saying that was crap.
- cbanek 7y 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 7y 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 7y 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.
- dathinab 7y agoWorse, hardly anyone ever updates them. But you still need to write, not necessary a speciation or tech document but all kind of notes and summaries for yourself. So that the you in two month can go back to a decision dinner two month before and reevaluate it with your new knowledge. Also depending on the company they might give you the task of writing a less technical describing if the system for e.g. investors. Lastly in my (little) experience asynchronous communication interleaved with small amounts of synchronous information discussions is king when it comes to the doing complex technical decisions (like which database or architecture to use for the next project). But then I don't have too much experience in this area so take it with a grain of salt.
- jefftk 7y agoThis depends enormously on the culture of your organization. And in a high-level role like this you're in a strong position to shape that culture.
- rabidrat 7y agoHow do you get people to read things? I've also written plenty into the void, and have no idea how to get people to actually read things (without being a jerk about it, which is not the culture I want to shape).
- stronglikedan 7y agoWhile I don't make people read things, but if the answer is in something that they should have already read, I do use their questions as a teachable moment. Instead of just giving them the answer, I tell them where to find it. Usually with a friendly note indicating that the docs are usually the quickest way to get an answer. The old teach-a-man-to-fish adage, if you will. Some people never learn, but I'm still not unfriendly towards them. Although, I do start to silently de-prioritize their questions over time. Most people do learn though, and they're the ones that start asking for clarifications instead of complete answers.
- jefftk 7y agoThings I've found useful: * Use a platform where it's very easy for people to give feedback. I've used Google Docs and Quip. * Write documents when there's real disagreement about how something should work. * Ask specific people for feedback on your documents. * Ask other people to write things, read what they write, and leave good comments. * Have a regularly scheduled meeting for reviewing team documents to get feedback. Anyone can sign up with a doc they want reviewed.
- edraferi 7y agoAlso: * Write clearly & concisely * Use good headers and provide a table of contents Here are some useful resources for writing better: https://www.plainlanguage.gov/ https://www.plainlanguage.gov/ http://www.hemingwayapp.com/ http://www.hemingwayapp.com/
- esmi 7y agoOn the other hand, everyone reviews the figures in detail. Therefore I’ve always used the text as a way to document the decisions behind the figure, mostly for myself, and to clarify any ambiguity in the figure itself.
- ilikerashers 7y agoAs someone currently migrating a rusty old Oracle enterprise system, please write documents. Migrations always blow up in complexity because someone didn't realise that there were 20 feeds from X DB and that a decade of hacking lived under the skin of their simple workflow system.
- fatnoah 7y ago>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. In the architect role, I write a lot of documents as well, but mostly for the purposes of: 1) Organizing my own thoughts 2) Summarizing for the benefits of upper management 3) Influencing discussions with peers 4) To serve as a record that someone interested can refer to The documents are generally higher-level and tailored to the audience that I intend to read it. In very rare (none?) cases am I ever getting detailed enough to get to this is exactly how we're doing it, since what I'm really trying to do is to set the overall direction and goals in pursuit of strategic objectives. I let the experts in individual domains handle the details. The entire process is also iterative. I build consensus through synchronous, high-level discussions ("wouldn't it be great if") and, through those, get a handle on the challenges faced by various orgs. I then try to coalesce that into something that benefits each org in some way, while still serving the overall objectives (developer velocity, flexible infra, performance, etc). My goal is to influence & inspire rather than dictate and own.
- jerf 7y agoI like to Ha Ha Only Serious that the ask for documents is just a standard technique for getting out of having to care about whatever it is you're talking about. If they ask you for documentation, and you don't have it, you automatically lose and they get to ignore you. If you always have it, eventually they stop asking you. (Until someone new joins and tries it on you.) Cynicism aside, it's useful stuff anyhow. Rubber ducking is a well-known debugging technique where you describe your problem to someone who doesn't have your context, even if it's only a rubber duck, and the mere act of describing will often reveal the problem. Writing documentation for other people is the closest equivalent for rubber ducking at the architectural level. When you're sitting there writing the complicated things you have to do to do X, you get an outsider's view of the situation. Take that and use it as motivation to fix the problem. Try very hard not to be just cynical about it and let your sensitivity to that signal become calloused... it is incredibly useful!
- michaelbrave 7y agoI've heard it said that a plan is rarely followed but the act of planning is invaluable. I wonder if writing documentation would fit similarly.
- letientai299 7y agoI, on the other hand, try to write technical document to not have to answer the same questions twice. When some one ask me anything that I have a doc cover it, I give them the link. If I don't, I answer, then check and update my doc. That works well for me so far.
- qznc 7y agoMe too. I have colleagues who do the opposite. They often complain that they don't have the time to write documentation because they have to explain stuff to people all the time. Thus, I believe writing saves time eventually.
- tj-teej 7y agoPeople should accept the fact that people are busy and often don't have/take time to read documents offline. I really like how Amazon mitigates that, you hold a doc review meeting. Everyone gets together, reads the document (in silence for ~30 min, or however long it takes), and then discusses. Then you know everyone has the proper context and knowledge for a good discussion.
- jasonlhy 7y agoI think document is good for filling the details, but it will not solve all the problem . And I kind of hate Architect with an extreme authority from top to the bottom and just assume people know everything. From my experience, casual communication between developers is an important factor in software development. The perfect role of architect I believe is an individual contributor. People just come to ask your idea and respect you to make the majority of design. And you need to help other to understand your idea.
- twhitmore 7y agoWrite an overview in narrative, and the rest in headings and bullet points. Keep the substance to 1-2 A4 pages. Nobody sane wants to parse more than a tiny bit of narration. Try to use Wiki, Google Docs, or shared docs in Office 365 if at all possible. Email chains are a collaboration fail, and Word docs are where information goes to die.