4 ms·
Writing documentation is painful, because it reveals inconsistencies and fuzzy areas in your design. If you're not paying attention, you may associate that pain
by metafunctor 5y ago
Writing documentation is painful, because it reveals inconsistencies and fuzzy areas in your design. If you're not paying attention, you may associate that pain with the act of writing documentation. In reality, the problem lies with your designs.
- larmstrong 5y agoThis. As a technical writer, this is one of the biggest pain points of the job. While writing the documentation, valid questions will come up regarding design decisions, but no one has the answers.
- MattGaiser 5y agoMost teams nowadays are agile teams, so there was never any real thought to why something was done a particular way other than it was the easiest way to complete the next ticket.
- agumonkey 5y agoTouching an interesting point.. maybe doc is just an ad-hoc rewrite in a different language. Maybe writing your program in different languages can refine the program to the point everything is clear.
- metafunctor 5y agoYep. A different language, a different viewpoint, a different audience. It helps to keep things simple, consistent, and familiar. If you're designing, say, a RESTful API, it's a good idea to write a couple of client programs in different languages. See what kind of hell you would be putting your users through. The idea generalizes, as well. Marketing is, sort of, documentation for the value proposition of your business. If you can't make the marketing work, maybe your business fundamentals need to be adjusted instead of hiring a “better marketer”.
- FooBarWidget 5y agoEmbrace this pain. I regularly run into the very issue you describe. I then update my designs. To me, documentation is also tool to verify my designs.