TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
A few annotations...
About Modular Reviews as a Model:If you look at the future of product development, things are getting way modular. Microservices are on the horizon -- product review itself is modular, where you review a service and then review how it integrates with the other services in your "product". Documentation will naturally follow. Maybe in search of a review model we should be looking at how dev reviews microservice architectures.
About every topic standing on its own:This is true up to a point. That point lies somewhere in the area of User Experience. How do you know the collection of topics is adequate until you see people work through the topics in context? Context includes the overall use case (using the product in a social setting), specific nested use cases (using specific features), and the dependencies/interactions between the topics in the collection. (You can go further and talk about visual design, interaction design, etc. but that's a different level of review IMO.) One topic can be fully correct and satisfy everything a specific SME demands, but it can still be of questionable value. In my experience you can't strictly rely on topic-level reviews. You can't strictly rely on so-called chapter-level reviews either (chapter being the old-school term for a subset of related topics), although it is useful to get. To assess the value of the whole package, you need to look at the whole package. I don't think a single product's documentation is huge enough to make us rely on statistical sampling of topics to infer whether they're valuable on a whole... Not for the usual product, anyway. I do think looking at the whole package roughly maps to integration testing in a microservices world.
About good-enough docs for good-enough development:You bet. We're in the modern world. I haven't seen a product spec since the turn of the century -- that's well over a decade. Agile rules the day, and you have to meet its demands. That means you understand the feature and document it as well as possible... And clean up the mess for the next iteration. Sorry, that's just the way it is (at least in my experience). So yeah... No solid starting point, and no solid finish line. When you're done modifying the product, you're looking for another job.
About dynamic vs chaotic:One of my favorites. If you look at the Agile Manifesto, you'll see that they borrow a lot of language from studies of self organization. Self organization is all about how patterns emerge at the edge of chaos. I feel your pain.Â
About a While In Progress Server:Yeah, I had that by definition in my delivery model -- until a reaction to the above-mentioned edge of chaos resulted in the dev team deploying a review process that shoved my stuff into a corner. Given room in my schedule (yeah right) I'll attack that as follows: Spin up a container for the doc I produce, with a simple upload model (the easy part); Implement integration with Jira so that any distributed doc system that has the integration enabled can link into a centralized internal comment system; Implement similar commenting with our social site so customers who have internet access can link into a centralized external comment system.Â
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
