3 ms·
In my new job I do a lot of writing; documentation, architecture (ADR's), and lots of details in the user stories themselves - although those are mainly for mys
by Cthulhu_ 7y ago
In my new job I do a lot of writing; documentation, architecture (ADR's), and lots of details in the user stories themselves - although those are mainly for myself.
But I have a fear. What if nobody bothers to read it? What if they start reading it but just glaze over because of the sheer volume of it? I mean the ADR's for example are a lot of 'internal' musings that I've considered.
I am a solo developer on this project at the moment (my colleagues do other stuff), so I've got nobody to check my work either.
At my last job, my colleague just said to not bother (we were err, very different personalities in that regard), it's wasted effort, I'm not going to bother reading it, just show me how to start it then show me the code. Which I guess works in smaller codebases in easier domains, but this won't be one of those.
Is there a similar article that emphasizes that people should read other people's writings?
- Vinnl 7y agoI think the trick is to write in a way that gets other people to read it, and in a way that's cognisant of the fact that that reading will be more akin to skimming. Gratuitous use of bullet points and bolding two or three key takeaways are the main quick hacks I use to in support of that goal. Longer-form writing and proper prose are more useful for e.g. tutorials, but things like user stories or other reference material should really be written to be skimmable, in my opinion.
- cypecoda 7y agoExactly. When I summarized a complex technical issue to a mixed audience, the TLDR version was in nested bulleted format, each line limited to ~5 words. Higher level bullet points were targeted at non technical readers and sub points aimed at the techie ones. Non technicals can opt not to dig further into sub points.
- jacoblambda 7y agoSome notes: I'd generally try to disregard the fear that your docs won't be used. At worst, they'll allow people to determine the original design intent and reconstruct how and why the project diverged at some point after you stop working on it. As long as the docs are part of the version control scheme for the project, you should be fine. If you however are using "share drive version control" aka a bunch of copies of the documentation for each release on a network drive separate decoupled from the project, it might as well not exist. If that's the case, you need to get it in version control. Sorry that was a bit of a tangent but I had flashbacks to a previous project. If you want people to read the documentation, make it concise. The ADRs can be verbose and logged as necessary. That's kinda the point of an ADR. They record the mindset and intent of the developer. Everything else however needs to be easy to jump into. Have a super concise summary that links to subtopics and put in the detail there. If you want people to maintain the documentation, integrate it into the build system/CI. If you have code examples in your documentation, they need to be unit tested so that the build system will warn you when the docs are out of date. Another avenue is to associate documentation with source code so that merge checks require documentation associated with modified sections of code must be checked off before commit. Getting this right is definitely the hardest part with documentation but when done well, it is immediately evident. Also I know I have seen articles like you mentioned but for the life of me I can't find them. If you come across them, I'd love if you could share some so that I can bookmark them.
- ivan_ah 7y ago> But I have a fear. What if nobody bothers to read it? This is definitely a big problem, especially in cases when reporting up the chain of command or sideways (to colleagues or other teams). People don't read. A big part of the reason seems to be the low expectation of value from any text. Since most writing is not well organized and rambly, people just assume it's not worth reading. And to be honest, they would be right most of the time... except when they are not. The problem is the well thought out email that summarizes all the info about the project from past meetings that took a day to prepare, contains all the important links to documents, and describes a well thought out strategy for next steps will get just as much attention as the average non-consequential email of the same length. Sometimes I think we need to have color coding for the hours that went into writing a piece of text, e.g. a paragraph showing in dark font indicates many hours and synthesis went into producing it (including decisions, consultations, planning, feasibility, etc), vs. a light gray text that is just a random suggestion. Such a color coding might help signal to the non-reader crowd (most people) that something is worth reading... something like nutritional facts.
- duckmysick 7y ago> What if they start reading it but just glaze over because of the sheer volume of it? Write concisely and in order of importance. The Inverted Pyramid model [1] is helpful. Key points answering questions Why, What, When, How, Where go up front. Then, important details. Finally, internal musings and background info go to the bottom. This way, the reader can stop at any time and they won't miss anything crucial. Another important tip is to refine the documents you've already written. Think of it as refactoring. Rewerite unclear, long sentences. Be consistent in describing the same procedures. Delete parts that aren't necessary anymore. Just like maintating the old code, it takes time and may seem as a waste of efforts. But it's well worth it. > I've got nobody to check my work either. Are there any other stakeholders that may be interested in what you're doing? Interns? Vendors? Ideally, your documents should be written so anyone can understand the main points and follow them. They don't have to gork the gory details and that's fine. Ask your collegues anyway, even if it's a first few paragraphs. [1] - https://en.wikipedia.org/wiki/Inverted_pyramid_(journalism) https://en.wikipedia.org/wiki/Inverted_pyramid_(journalism)