Writing an Article for Your Automation

Table of Contents

Tips and advice for promoting your automation with an article

A great article is self-PR; it publicizes your automation and increases your visibility as a developer. Your article isn’t just a tutorial on how to set up your code; a Read.Me takes care of that. Tell your story of how you tackled a problem, how you approached your trials and errors.

Here are some tips on writing an article for your code on Medium and other publishers:

General Tips

Spelling and Grammar

  • Double-check for spelling and grammar before you publish your article.
  • Use spelling and grammar checkers, such as Grammarly.

Readability

  • Most people will be skimming through your article. Make your article easy to digest by breaking down long sentences and long paragraphs.
  • Break down large chunks of information under headings.
  • For lists with 2+ items, break them down into bullet points.

Language

  • Use plain English and explain your concepts in a way that beginners can understand them.
  • When using jargons, explain their meaning.
  • Provide links to references or background knowledge if possible.
  • Spell out acronyms the first time you use them. Example:
    HfLA (Hack for LA)

Keywords & SEO (Search-Engine Optimization)

  • Tag your article with relevant keywords - the program you’re using, type of automation, who your code helps, etc.
  • Include relevant keywords in your title and first paragraph so that your article shows up on the front page of search results.
  • If you can, sprinkle variants of your keyword naturally throughout your article.
  • Provide links to your other articles when relevant.
  • When linking to outside sources, make sure the websites are trustworthy - this contributes to ranking higher on search results.

Title & Subtitle

  • The title is short (less than 25 words) and grabs the reader’s attention (provocative). It’s usually a problem statement (offers a solution to a problem) and frames your project so readers know what to anticipate as they read further.
  • The subtitle invites your audience to read further. It expands on details you couldn’t put in your title. If your title is somewhat bland, you can put a little twist in your subtitle to draw your readers in.
  • There are times when you can omit your subtitle; a super long title, or one that tells everything about the article by itself.
  • You can also make your title eye-catching by using emojis (especially if your program has an associated emoji).
    Examples:
    How I Eat For Free in NYC Using Python, Automation, Artificial Intelligence, and Instagram (Christ Buetti)
    How I automated my job with Node.js (Shaun Michael Stone)
    The Cure for Homelessness. – How Tech can Bridge the Income Gap. (Eric Elliot)
    We rendered a million web pages to find out what makes the web slow (Lars Eidnes)
    Continuous Deployment with Docker🐳 and Github Actions🐣 (Ben Swerdlow)

Header Image

Provide an attention-grabbing image. Some possible variants:

  1. Colorful (logos of the programs you’re using)
  2. Emotional (especially if your code solves a real-world problem)
  3. A visualization of your automation. (This saves time for readers looking for specific solutions.)

Structure

Structure your article like a story - it should have a beginning, middle, and end. In this guide, we’ve divided the article under 3 main sections (headings): Introduction, Body, and Conclusion. You can reword these steps in different ways, or use your own structure - The simpler, the better. Remember to add your own subheadings for in-between steps.

Examples of headings:
What I did; How I did it; The Results
What; Why; How; Conclusion

Introduction

  • Briefly explain what your automation does. (i.e. what problem(s) it solves.)
  • Include a link to your GitHub repository or where you published your code.

Body

  • Why did you start creating your automation? (e.g. Was it out of annoyance or necessity?)
  • What prerequisites do you need to use your code? (What programs)
  • Briefly explain how to set up your automation.
  • Give examples of how your automation can be used in different programs.
  • Give visualizations (screenshots, end results, illustrations, workflow charts, etc.) to back up your explanations and break up large blocks of text. The more relevant pictures you have in your article, the better you’ll be able to get your points across.
  • What were your results?

Conclusion

  • As you close the article, briefly summarize the content and explain what you learned from this project. Once again, link your readers to the GitHub repository or platform where you published your code.
  • Suggest readers to check out your other articles if they are relevant to topics mentioned in this one.
  • Open room for discussion or suggestions for potential improvements that could be made to your automation.

If you have any other suggestions for this guide, please contact us at 100Automations@hackforla.org.