In this case study on docslikecode.com, Jennifer Rondeau shares her story of gaining the trust of her developer coworkers so that she could edit code comments for a remote management web service at Symantec. This is an excellent, in-depth piece, and I really appreciate her writing it up to share.
While Jennifer was writing up the story on GitHub and I was reviewing the case study, I asked her to clarify a couple of points she made about fully integrating with the development team. One was “Doc management was continually concerned that putting a writer into the code — writing code comments and code samples — would set developer expectations of the writers too high.” Ouch. She goes on to say that their root concern was about the extensibility of the model – they didn’t think it could scale across teams. While reviewing, she clarified to say that management didn’t want devs to think they could offload work that they ultimately were responsible for themselves, maintaining good code comments. Also, management found that the tech writers had much more code-savvy than originally thought, and the empathy and advocacy that writers could provide was well worth the risk in the embedded model.
Another point to clarify while drafting the case study was about doc build automation. In the end, they decided not to automate the doc builds as part of the code builds. I wanted to know: Was it a dev resources problem where doc builds were not prioritized high enough as compared to work on the services? Or, management didn’t want to invest the time? Or the writer didn’t find a way to do it herself? Or maybe the automation time savings wasn’t quite big enough for attention? She said, “Ultimately, the decision not to automate the Javadoc made sense — there are always pain points on either side of a decision like this.”
You can hear more from Jennifer in “Docs as Code: The Missing Manual,” co-presented with Margaret Eker at Write the Docs Europe 2016.