Recently, I was fortunate enough to get a chance to write a case study on HP.com architecture for The Server Side (TSS), a community for Java developers with upwards of 600,000 members. This Running Diary is separated into three pieces and details the whole process, starting with how I got approached about doing it, moving on to the writing process and how difficult it can be to accept negative feedback (Part 2), and finally some of the surprising things that happened in the aftermath of the article going live (Part 3).
Over the first 6 months of this blog, among the most eye opening metrics was the amount of traffic and conversions of visitors to subscribers I received from making comments over at TSS. It wasn’t surprising, since the typical audience for a site devoted to Java development is also the target I’m trying to serve with the things I write here and based on my job, I have a decent amount of credibility on that forum so I was getting a lot of crossover. Because of this, I was getting ready to approach the editors about an article post when, based on the techniques I described in my review of The Virtual Handshake regarding transparency and branding yourself online, they approached me instead. While they were more interested in a technical slant on my HP.com activities than in the career topics I write about here, I was excited for the opportunity regardless of what they wanted me to discuss.
We exchanged a few emails to get a feel for what kind of topics they wanted me to cover (a 50,000 foot view of the HP.com domain followed by a zoom in on some specific aspects, including how Java is used to solve problems we have) and how long the article would need to be (less than 3000 words). With that settled, I was ready to write.
Then, it occurred to me: I better make sure I don’t get fired over this.
HP Legal: What’s proprietary and what isn’t
How much of our architectural plans are sharable? At what point are you giving competitors too big a view at what you are doing so they gain an advantage on you? I didn’t know the answers to these questions, so I sought help from the HP Legal department.
The first question I got asked by my contact there was, “What’s in it for us?” Meaning, why write this article at all? It turns out “Because it’ll look good on my resume” isn’t a good enough answer. In my case, given that HP is in the business of selling products and services to IT departments, exposing how our own IT functions passes the litmus test since it delivers some benefit to HP. Then, Legal had a few other suggestions that proved useful:
- Get your materials reviewed by your management before you publish them. That may sound obvious, but it is a good reminder. I went ahead and had a superior along the technical path of jobs take a look too, just to be safe.
- What would a competitor do with this information? Imagine yourself being your counterpart at a major competitor. If you read this article, what would you then be able to do differently to get an edge? Are there any security concerns about describing a software architecture publicly?
- Stay away from vendor specifics. Although we use a lot of vendors to help us deliver solutions, leave it up to them to tout our relationship. Don’t advertise it for them, especially in a medium where the article may stay around longer than the relationship does.
- Be as generic as you can while getting your points across. The biggest effect of this point was to not use internal names for most architectural components but to describe what they did.
Now with the parameters of the submission in place and some guidance to make sure I wouldn’t get fired for accidentally revealing too much, I actually had to write the article.
Writer’s block and getting unstuck
When the page is as empty as the ideas in your head, a blinking cursor in Microsoft Word is like mocking laughter. I found that with all these rules I now had to adhere to and with the pressure of not sucking, I just couldn’t get started. I was worried about the tone not being too boring, the context for why we made certain decisions going on too long, and fitting in the 3000 word length limit while still following the HP Legal guidelines.Then, I remembered to follow my own advice.
Much like I did for her sewing project, my wife was willing to listen to the combination of problems I was having. While I was explaining these restrictions to her, I realized that I needed start with reasons that drove the architecture before I described the architecture itself. Once I got over that organizational hurdle, it flowed pretty well. Exactly like the sewing incident, she solved my problem without having to say a word.
With the article written, I was ready for feedback. I was hoping for the “wow, this is perfect as is” kind of feedback and got a little defensive when I got something less flattering, but ultimately more useful when I got over myself. This, and the remainder of my experience writing this article, is covered in Part 2. What happened afterward is discussed in Part 3.