Recently I wrote my first technical blog post for another site and it was an interesting experience. Being primarily a Drupal shop, Hook 42 asked me to write a Drupal 8 technical article about whatever topic I wanted. After much thought, I landed on the topic of Consuming JSON APIs in Drupal 8.
What interested me most in this topic is the broad range of technical details involved, especially when seen through the lense of Drupal 8. In the article I wanted to present the information in a way that would be useful to developers of any skill level. This meant I would need to cover the following information for different readers:
- Beginner: Fundamentals of consuming APIs with simple PHP functions, explaining the terminology and each part of the process.
- Intermediate: Repeating those fundamental concepts using a popular PHP library (Guzzle) and describing why this approach is generally better.
- Drupal – Intermediate: Including the Guzzle approach into a form that becomes useful within Drupal 8 (providing a block). And explaining why it’s valuable to make use of the Drupal-specific approach.
- Drupal – Advanced: Show the same example while using Drupal’s best practices so that the final example is more valuable that the parts.
Overall I achieved what I set out to do in the blog post and I’m very happy with it. It contains valuable content for developers of almost any level in the post. And I foresee myself referring back to it in the future. Both of which is the mark of a great article in my opinion.
Writing for an audience
Mosts blog posts I write on this site are for an audience of one… myself. Often they come from something I’ve learned (or had to re-learn) that involve a specific theory or approach to solving a problem. I can’t tell you how many time’s I’ve started working on a familiar problem and visited an old post of mine to get a head-start on the solution. I call this approach “writing for future-me“.
Some examples of blog posts I’ve written for future-me:
- Git & SSH – Too many authentication failures
- WordPress Rewrite API Examples
- Dynamically Add Items to WordPress Menus
Other times I’ll write the article for past-me. These articles are content I wish I had found on the internet when I was getting started as a developer. Though I don’t often refer back to these posts, I sometimes find myself sharing these articles as answers to questions from other developers. Historically I’ve found that some of these posts are the most popular posts on my site and I am very glad to have written them.
Some examples of articles I’ve written for past-me:
- A Very-Introduction to Drupal’s hook_form_alter()
- How to Create a Simple PHP Templating Function
- And its successor, a Simple PHP Templating Class
Writing for another website
An interesting part of this experience for me was around the idea of writing content for someone else’s website. As mentioned before, this is the first time I’ve written an article for a site where I wasn’t fully in control of the whole process.
On my site it is up to me to determine an article’s concept, content, tone, design, editor, code, references, along with performing marketing and SEO. This amounts to a significant amount of both freedom and responsibility. Because I’m not an expert in grammar and don’t have an editor, I’m often finding mistakes in articles that were published months or years ago.
When writing for Hook 42, I had the help of a team to assist with much of this. The architects team helped me find a topic that interested me, then I wrote what was essentially a first draft. Adam Bergstein reviewed it for content and provided some great suggestions for adding clarity to various sections. And Genevieve Parker took on the role of editor, finding what seems like a billion grammar mistakes, while leaving the light-hearted tone of the original content in place (Cat Facts!).
Ultimately the article ended up much better than I could have achieved on my own, and the experience has encouraged me to do it more.
Result – a module for Cat Facts
Module on GitHub: Cat Facts
This module includes the following:
- Drupal 8 Service
- Drupal 8 Block with Dependency Injection
Discussion
“writing for future-me“.
That’s deep.