2018 Review: a Year as a Documentarian
I had started 2018 with a personal resolution to write more. This resolution took two forms. On the personal side, I wanted to write at least one blog post each month. On the professional side, I wanted to incorporate more writing / documentation into my job.
What Went Right
Doing more documentation and writing as part of my job was a huge success. I created at least 4 readthedocs sites and helped make documentation for various projects accessible and part of the development process. Part of this took the form of explaining user docs vs. developer docs to my teammates; part of this was documenting the target audience for the documentation itself.
I also started using org-mode to create a few literate documents for small, one-off projects. The most successful example was a document about a file migration project. Through org-mode Babel blocks and tangling, I was able document the whole complicated process in one place. In addition, I could capture results and calculate statistics as I went. The one file became documentation, workflow, results database, and reproducer all in one. I did a short presentation to my peers to explain the project and get them excited about org-mode!
Overall, documentation has become a consciously essential part of my job. First, being sure document many parts of my job makes me better at what I do. I also realize that if I ever want to take grow in my career, I’ll have to find others to do tasks that I no longer have space for. This hand-off process is precisely where documentation comes in.
What Went Wrong
The biggest lack of success was my goal to post to my personal blog. I managed to write 14 posts, but these were all posted in the first half of the year; I’ve been silent since August.
Truthfully, I never really fell into a groove with dedicated personal writing time in front of my laptop. More often than not, I found time during work-related travel or while out and about. As more of my travel workflow moves to the iPad and iOS, restricting my blogging to a full emacs installation is untenable.
The final blow to my streak was some travel and major events that happened over the summer. With the streak broken, it was easier to leave my blog abandoned. Until now at least.
Looking Forward
My personal theme for 2019 is communication.
Despite working for a year at writing and documentation, I realize I suck at communication. Particularly casual and personal communication. I think that one of the reasons I think so hard about documentation (and who the audience is and what exactly I’m trying to get across) is because communication itself is something I struggle with.
To that end, I really want to make this blog a thing. So I’ll be trying again, this time more publicly: I resolve to publish at least one post each month.
How can I enable myself? First, I need to figure out a workflow to publish from my phone. I have quite a few drafts that are stuck in purgatory in my phone Notes app. Second, I need to allow myself to write posts that aren’t technical. Hopefully this post is itself a good start!
Comments
Comments are sent directly to me and may or may not be posted for display on this page.