Engineers don't use the product they create, so they don't see or care about user-facing docs. The way to get them to care about doc is to introduce them to the doc for the things they use every day.
The first step is to find the internal tools that engineers use all the time. Then don't fix those docs, but have the engineers write it, or collaborate with them about it. You can help them build their writing skills.
Even at companies where the ratio of engineers to writers is decent, there's still too much work for writers. (And at most companies, the ratio isn't decent.)
Where doe knowledge exist? If R&D processes aren't written down, you have lost copious amounts of engineers' time. Where does knowledge exist if it does not occur only in an engineer's head? What happens when one leaves? What happens with new people? You lose R&D productivity where people have to take time to find out.
Having internal processes documented increases R&D productivity. Hosting government data includes audits of your processes. If you have your processes documented, you're going to be prepared for success.
Companies are reluctant to think about internal documentation. Engineers get worried when they have to explain things over and over. The initiative to get your internal processes documented can come from that.
Find internal champions, engineers who are frustrated about things that are not documented. Then nurture them and give them a forum. Host a cheese and whine session and invite engineers. Get people together, find a way to organize people who are like-minded.
don't go it alone. The engineers who are complaining about no docs know where the problems are and have their own ideas. Provide the organization and project management skills.
Have a "fix the docs" hack day. "You didn't build the road. You didn't litter on it. But for a single day, can you 'adopt' a road and clean it up?" Then give clear guidelines of what they can do. Afterward, it's vitally important that you socialize the results. Have to recognize the engineers who helped.
Some text is always better than no text. It's a culture change: You must write it down.
Some engineers will claim that good code documents itself. No, it doesn't. The comments tell only what it does, not how or why.
No comments:
Post a Comment