Contents
Six weeks have elapsed since the official start of the Season of Docs project, which makes it a good time to reflect on the experience so far. Apparently Google thought so too because they sent me a little questionnaire this week asking how it was going.
Program overview
Overall the program has been fantastic. This was my first experience with open source, and my yelps1 at the command line every time I sent a pull request have transformed into surprise exclamations when there are no errors. I’ve been getting an insight into agile software development as sometimes the user interface will get an update as soon as I’ve documented it but you just have to roll with it. It’s exciting to see the platform develop in real time and be a part of it.
The biggest learning curve for me was in relation to using Sphinx to document which took a couple of weeks to really get used to.
Here are my takeaways from the last six weeks:
God Bless Stack Overflow
If I could buy this site a Christmas present, I would—it saved my hide on so many occasions. There’s something very comforting about seeing someone else have the same issue and the effort from programmers to answer. I found answers here to almost every little issue I had.
The only challenge was finding the right keywords to search. I’m not saying anything groundbreaking when I say that developers speak their own language. One example comes to mind: I submitted my first pull request and got some comments back from reviewers to make some changes. So I started Googling different variations of ‘how to update a PR’ but the results were frustrating. It took a few hours before I stumbled upon the correct terminology—’amending a commit on a pull request’. Who knew?
Developers are not scary
I had several occasions to ask questions to the developers about the software and I found them relatively quick to respond and help out. One even set up a phone call to explain a software feature in detail. Having said that, I only contacted them after scouring through all the available resources first. I heard this on a Write the Docs (WtD) meetup as well:
DON’T ask “So tell me about this feature/product.”
DO ask something like “I went to this screen and noticed this happened, but I hadn’t seen this before when testing. What does this do in terms of task A?”
See the difference? The latter shows you took the initiative to figure out the problem yourself, and your question becomes more specific.
Communication is key
This is clichéd but bears repeating—whatever issues you’re having, whether it’s not getting a timely response on queries, software errors etc.—let your mentors know. I’ve been meeting with them on a weekly basis since the project began.
This is in contrast to the usual experience of technical writers as I learnt at WtD. As other tech writers talked about their experiences, there was one factor that seemed to be prevalent: they all had a feeling that technical writing was somewhat devalued amongst their colleagues. People would often ‘forget’ to let the technical writer know that a product was changing, which in turn would impact documentation.
To digress for a moment, I’ve been experiencing a bit of this in my own job (outside of SoD) but I realize it just comes with the territory. Business analysts and developers are busy and don’t intend to ignore the technical writer—so it’s up to us to find ways to pry.
One tip I heard at WtD was to corner them in the kitchen (or some other neutral place) and ask a general ‘So what are you working on at the moment?’ — people love talking about themselves so this is a neat way to figure out what’s in the pipeline.
This makes me appreciate my weekly meetings with my Season of Docs mentors even more. While I initially thought it was a bit much, I’m glad they set it up this way, as the frequent communication has made me feel very supported.
Conclusion
While the project officially ends November 22, it’s hard for developers—and consequently technical writers—to neatly wrap up building and documenting a new interface by a certain date. I’m quite eager to still be involved with the organization after Season of Docs ends, and my mentors seem keen to have me on board as well. This for me is the biggest advantage of participating in this program—your experience doesn’t have to end when the program does.
0 Comments