DEV Community: Stephanie Morillo

3 Tips for Developers Writing their First Book

Stephanie Morillo — Wed, 30 Jun 2021 22:50:13 +0000

Photo Credit: #WOCinTech Chat

So you want to write a book? Or maybe you don't — but you've certainly seen more and more developers in the community publishing their own books, right? Since I published my first eBook last winter, I've seen the number of self-published books boom. Let's talk more about this format!

Books are a great vehicle for diving deep on a topic and having a very clear outcome for the reader. You have to map out clearly where you're taking the reader and why, and you have to articulate what they'll be able to do or learn at the very end of it.

Here are some tips I have for anyone who is thinking of writing a book.

Tip #1: Conduct market research

The purpose of market research isn't to dissuade you from writing your book. You'll discover if there are books similar to yours in the market and will help you figure out what makes yours different. When we go into a grocery store, we may find ten brands of milk for sale. But each one uses something distinct to make it stand out from the pack. See if there is a gap in what's available that you can use to your advantage, either as an angle to explore with your book or as a talking point when promoting it.

How to do this: Search engines, browsing the catalogs of tech publishers, searching sites like Gumroad, Product Hunt, and other eCommerce places. Look for topics that are similar to yours and read the descriptions of those books, check out their table of contents, and read reviews. Understand where the similarities are and what is different between those books and yours.

Tip #2 Decide whether or not to self-publish

People who choose to self-publish versus those who decide to go the traditional publishing route want different things. Self-publishing is great for anyone who wants to build and sell digital products, promote their business, and control pricing. Traditional publishing is a great fit for anyone who wants the backing of a reputable publisher supporting their work, anyone who wants to write without the hassle of handling book editing and production, and to get their book in front of audiences unfamiliar with their work. Get clear about what your goals are and don't feel pressured to go one way or another because other people are doing it.

Bonus points: Set up a casual conversation with peers who have self-published and peers who have published. Ask them what their goals were, why they went with the route they chose, what the pros and cons are of each track, and how they promoted their book. (Don't know anyone? All good! I talk more about each publishing track in-depth in The Developer's Guide to Book Publishing.)

Tip #3: If you self-publish, hire an editor or two

An editor or two is an absolute must if you're self-publishing. You're creating a product that is meant to be read by others, and the quality needs to reflect the work you put in and the experience users expect to receive after they pay. An editor can do more than fix typos; they can help you with structure and formatting, spot inconsistencies, and make recommendations for things to add and improve. I like hiring two editors and having at least one peer review of my eBooks to ensure the edits and feedback are comprehensive.

How to do this: Ask your network for referrals, or look at freelance marketplaces like Fiverr (affiliate link), Wordy, and Upwork. Read reviews, read what services each platform offers, and look at pricing. Determine your budget ahead of time and filter for editors who meet your budgetary requirements and editing needs.

This post originally appeared on my blog.

I'm Stephanie, a Content Strategist and Technical PM. If you liked this post, visit my website for more content tips and to learn more about my work!

What are your thoughts on search engine optimization (SEO)?

Stephanie Morillo — Fri, 28 May 2021 16:07:53 +0000

Hey all,

I'm doing some research on developer experiences and sentiments toward search engine optimization (SEO) and want to hear from you.

What comes to mind when you hear SEO?
Have you ever spent any time on your SEO? Why or why not?

Thanks in advance!

Introduction to SEO for Developers

Stephanie Morillo — Fri, 26 Mar 2021 15:00:29 +0000

Photo credit: #WOCinTech Chat

According to a 2012 research study commissioned by the Pew Research Center, “91% of adults use search engines to find information on the web [and] on any given day, 59% of those using the internet use search engines.” It’s also widely known that software developers use search engines for everything from troubleshooting to finding documentation. (And if you’re really curious, I found a peer-reviewed research paper about this, too.) Developers and general internet users alike often start their research as a query in a search engine bar.

This simple mechanism (to us end-users) allows us to retrieve information at a moment’s notice. The complexities of search are abstracted for us. We don’t have to think as hard about how a search engine knew exactly what you meant and how to was able to crawl through billions of sites to serve up the most relevant article to your query. On the one hand, we have algorithms that power search engines. We don’t know exactly how these algorithms work but can posit based on behavior (and some do share a few factors that affect how sites rank). And on the other hand, there are numerous professionals trying to figure out how to optimize websites so they land on the first page of search results. This process is called search engine optimization, or SEO.

So how does SEO relate to software developers? You may have a freelancing business or a personal blog, or maybe you work on a site engineering team. In all of these cases, you likely want your site to get indexed in search engines to attract visitors who may not know about you, but would find your content (or business) interesting. Since the vast majority of internet users start their research in search engines, you want your site to be there.

Let’s say you’ve started a personal blog on a domain you own. Even if you’re writing for yourself, chances are you want other people to read your work. You likely share your blog posts on social media or syndicate them to developer blogging platforms like DEV Community. You may have looked up techniques for building an audience or getting more readers on your blog. What if you don’t blog; you screencast on YouTube instead? SEO will benefit you all the same, whether a visitor starts their search in the Google search bar or in YouTube’s. Using SEO helps you send the right signals to your prospective visitors. It’s how you tell them, “Hey, I have the answer to your question!” or “I offer the solution to your problem.”

What is SEO?

Search engine optimization (SEO) is the process of improving site content to rank higher in search results. According to a 2017 article from Forbes, only 25% of internet users scroll the first page of search results. (There’s an industry term for these pages: search engine results page or SERPs.) Thus, companies, individuals, and other entities have two options to make it to the first page: through paid search advertising or search engine optimization. And people pay lots of money for tools and access to experts in order to rank higher in organic search results. (Website traffic coming from non-ad search results is called organic search. Traffic coming from ads in search results is called paid search.)

But the sobering truth is that no one — not even the most expensive and experienced SEO consultant — can guarantee you’ll end up on the first page, no matter how much you optimize your content for search engines. There are lots of ways people try to “game” search algorithms using SEO even though their content isn’t good or relevant. This is called SEO spam, and it’s lucrative. In other words, you could spend considerable time and money to learn and use the many SEO tools and techniques out there and still not make it to the first page.

What Search Engines See on Your Site

When many developers think about site structure or architecture, the first thing that comes to mind may be a web development framework. Developers will consider how the framework structures information, how and where content is stored, and how to make changes and updates to a page from the site.

But content strategists and even search engines see structure differently. Site structure, from this perspective, refers to the way information (webpages, text, images, and other content) is organized. If your website is a house, the site structure is the frame (the wooden or steam beams that are the house’s “skeleton”). The site structure, built from a blueprint, serves as the foundation. It’s what differentiates the rooms of a house and their access points, so house frames also account for doors, windows, walkways, and other elements pertaining to a specific room and the surrounding space.

We create websites for a specific purpose, and people visit our sites to fulfill a specific need. They visit sites to get informed, access information, or change information. Our job is to help people take whatever actions they need on our site by providing them with the right information and pointing them in the right direction.

How Search Engines Work

Search engines work by crawling websites to see how information is organized. Oftentimes, websites will create and submit a sitemap (in XML format) to search engines, which shows the way webpages are categorized. Sites will also submit a “robot exclusion standard” file, also known as a robots.txt file, which further tells search engines which sites to crawl and index and which sites to omit from search results. For example, an e-Commerce site might want its products, blog, and about pages indexed, but will want to omit the checkout page and the purchase confirmation page. If you have members-only pages, you can also omit those, too, from search engines by listing them in your robots.txt file.

On the site itself, search engines look for information about information (or metadata), like page titles, headers, descriptions, links, and structured JSON. They will also look for keywords that they will use to index pages in relevant search results. Most of this metadata is available in HTML tags and attributes. (Many site builders and static site generators will simplify this for you, so you don’t actually need to touch HTML in order to have this metadata added.)

Search engine crawlers are not “smart” in that they cannot infer what something is about based on “looking” at a page the way we can. They cannot tell whether the content of a webpage is valuable, relevant, or high-quality. All it can do is determine relevance based on the keywords being used and the relationships between various pages on a site.

While we don’t know everything about how individual search engines work (the Google search algorithm reportedly factors in over 300 elements in search results), we know that search engines also consider page load times and HTML tags in how high a website ranks.

You can decide to “hide” a page from search results, like checkout pages on e-Commerce sites, pages that are a part of a member’s only section, or pages that have been removed from your site.

What Your Site Should Allow You to Do

No matter the platform you’re using to host your site, you want it to allow you to do the following:

Create or generate a sitemap
Customize your URLs
Create redirects as necessary
Add structured data
Craft descriptions and edit page titles
Add alt-text to images
Compress images
Create 404 pages just in case

In conjunction with free SEO tools, having the dexterity to edit these aspects of your site SEO gives you more ability to influence the way your content is structured which affects not just rankings, but your site experience.

Benefits of SEO: A Short Case Study

In 2017, I was responsible for managing Bundler’s content strategy. (Bundler is the dependency manager for the Ruby programming language.) Part of my role was to help make the documentation on the Bundler.io documentation site easier to find for visitors.

I conducted an SEO audit of the Bundler site and competitive analysis of three other open-source software documentation websites to better understand what they were doing well and how we could apply those best practices in our documentation.

The SEO audit was the most enlightening part. I spotted issues with titles, which made it hard for visitors to understand where they were in relation to the rest of the docs site and didn’t clarify what visitors would be able to do or learn. I created a standardized titling scheme, updated titles for the most recent release, and added more copy to the documentation landing page.

In the quarter that followed the audit, we observed the following on our documentation site:

An 8.38% increase in total page views over the previous period
A 7.17% increase in total users finding the pages via organic search over the previous period
A 7.78% increase in average time on page over the previous period

In summary, these were really impressive changes! We were able to accomplish this work by setting aside the necessary time and effort to understand the problem and leverage SEO to help us create more clear messaging and improve organic search results.

Next Steps: Where to Go From Here

There is no shortage of sites, books, and tools that you can use to learn more about SEO. I encourage you to search through the official documentation of any framework or platform not listed for SEO-related guidance.

The following tools are all free SEO tools that I have used to improve my site's SEO. They range from coming up with content ideas, to creating structured JSON for different pages on my site, to monitoring site performance and getting ranked on search engines:

Ubersuggest: https://neilpatel.com/ubersuggest/
Answer The Public: https://answerthepublic.com/
Schema.org (to learn about structured JSON for SEO)
Technical SEO Markup Generator: https://technicalseo.com/tools/schema-markup-generator/
WebPageTest: https://www.webpagetest.org/
Google Search Console: https://search.google.com/search-console/about
Bing Webmaster Tools: https://www.bing.com/webmasters/about

This post originally appeared on my blog.

I'm Stephanie, a Content Strategist and Technical PM. Visit developersguidetocontent.com to learn more about my work!

What's holding you back from creating as much content as you would like to?

Stephanie Morillo — Thu, 25 Feb 2021 15:15:32 +0000

It's almost March, and many people set goals at the beginning of the year when it came to content creation. Maybe that's the case for you, or maybe you've only begun on your journey.

If so, how are you doing so far? Are you creating as much content as you wanted to? If so, what's helped you, and if not, what roadblocks are you facing?

What is the best blogging platform for developers?

Stephanie Morillo — Mon, 11 Jan 2021 15:02:59 +0000

A question I get from developers who want to start their blogs is what’s the best blogging platform for developers? With a multitude of static site generators, content management systems (CMSs), site builders, and hosted, developer-focused blogging platforms to choose from, developers have lots of options. That’s both good and bad: good in that developers have plenty of flexibility, but bad in that it leads to decision fatigue.

There are pros and cons to each option and you may outgrow your platform in the future. The static site generator that initially gave you great site performance may not easily scale once you get to n blog posts. The site builder that enabled you to drag-and-drop everything from new text fields to animations may also prevent you from removing custom JavaScript that runs on each page, impacting your site performance. A blog that was hosted on a blogging platform may eventually need to morph into a website that is optimized for attracting new clients, forcing the team to build and migrate to a self-hosted site. We can’t plan for all future outcomes.

So the answer to “What is the best blogging platform for developers?” can be found by asking yourself a series of questions. You can’t anticipate what your future needs will be, but you can look at your existing needs to figure out the next best step.

What will the site be used for primarily? Will it be primarily a blog or a landing page that points people to your resume, contact information, and projects? Will you be using it to attract business? Are you going to sell products or services on your site?
How much time are you willing to spend building and maintaining the site?
How often will it be updated? And when you do update, what types of changes are you willing to make: will it be mostly publishing new content, or will you be making changes to the design, site structure, and plugins?
How important is flexibility for you? Do you want to have control of everything including server-side maintenance, or do you want some of the work abstracted for you?
How much are you willing to pay? Are you willing to spend money to have some things taken care of (like hosting, security, and other site updates) or do you want to spend close to nothing?
How much are you willing to learn? Do you want to learn about databases, load balancers, and content delivery networks (CDNs)? Do you want to learn about search engine optimization (SEO) and implement SEO best practices on your own?
How important is branding? Some blogging platforms make it difficult to remove their logos from your site or change the design to your liking.

How I decided to build my site

I did this exercise for the first time five years ago when I built my website with Jekyll (a static site generator) and then three years ago when I migrated to Wix (a site builder). I originally wanted to accomplish three things with my Jekyll blog, listed here in order of importance:

Learn how to use static site generators

Learn how servers work

Have a portfolio site where potential clients could find out more about me and my work

In the beginning, this setup worked very well for me. I didn’t want to touch HTML and CSS so I found a nice template. I wasn’t blogging much so I didn’t need to update it regularly. But a year or so later, I wanted to make changes to the template and blog more. The experience caused so much frustration that I didn’t update as much as I wanted to. Some of the issues I faced included:

Making changes to the template because I didn’t want to spend time in the code
I couldn’t serve my site via HTTPS. At the time, Let’s Encrypt had just come out and the process for generating a TLS certificate for Apache web servers worked well. But I was using NGINX as my web server and no tutorial I found could make it work.
Making a single change on a page — like editing a sentence — required ten steps to complete. I wanted to cut it down to three steps or less.

I was satisfied with what I’d learned about static site generators and servers, but it was no longer my priority. My new priority was to have a site that would serve as my “business card on the web”. I wanted to make endless changes to pages and content without having to code or hiring a web developer. So I moved my site to a site builder that took care of a lot of that for me. Over time, I’ve learned more about what I can and cannot do with my existing site platform. There may come a time when I will need to consider migrating to something else, but it does everything I need it to for now.

Every platform has pros and cons

Every site builder, blogging platform, content management system, application framework, and static site generator is optimized for specific things. Very, very few do everything well. (I know this because, as a content strategist, I often complained about whichever content management system I was using to manage blog posts.) It doesn’t matter if the platform has shortcomings; it does. What matters is if you can live with those shortcomings.

Ultimately, the best blogging platform is the one that makes it easy for you to blog. If you enjoy the platform’s user experience and creating or publishing content isn’t a hindrance, that’s what’s most important. Few people care about what platform you’re using; your content matters more. But if building a blog to demonstrate your experience using a specific stack is important to you, choose the framework that best suits your needs. You can always change your mind later.

Regardless of which platform you choose, be sure to do the following:

Take regular snapshots of your content. Consider putting all your content in a repository. This will help you manage your blog posts, copy, and other assets, and can facilitate migration to a new platform. Your repository can be anything: a Google Drive folder, a folder on your desktop, or a GitHub/GitLab repository. Keep your content up to date on both your personal site and in this repo.
Read as much of the product documentation as you can. Familiarize yourself with the platform, its features, and limitations.

In summary, the best blogging platform is one that meets your current needs and goals. Do as much research as you can into the multiple platforms available to understand how much time and effort is required to initially set up and to maintain over time. Keep your web content updated and save a copy elsewhere in case you need to migrate or restore content from a backup. And finally, familiarize yourself with your platform’s features, limitations, and workarounds.

This post originally appeared on my blog.

I'm Stephanie, a Content Strategist and Technical PM. Visit developersguidetocontent.com to learn more about my work!

5 Ways Software Developers Can Improve Their Writing Beyond Blogging

Stephanie Morillo — Sun, 20 Dec 2020 13:18:38 +0000

This time last year, I placed a bet on the idea that software developers wanted to write more content and become better bloggers. This idea is not new, it's not novel: software developers have been blogging as long as blogging has been around and the field has benefitted from developers who have generously shared their knowledge in the form of articles and blog posts. In less than one year, over 1,200 developers have purchased my eBooks on content creation and have started their own blogs, newsletters, podcasts, and screencasts.

But while I've had the opportunity to see developers pour their writing capabilities into blogs (and there are plenty of good reasons to blog), the same level of enthusiasm isn't there for another form of writing that is just as impactful: business writing.

What is business writing and why is it important?

Business writing takes the form of emails, presentations, reports, and internal documentation, among other things. It includes everything from your team's quarterly OKR document to the technical spec you create for work items. This is the writing that keeps everyone in your workplace informed, trained, and it keeps things moving. Work gets done through business writing and business communications.

Written and spoken communication, we know, is a crucial skill to cultivate. It will affect everything from the amount of influence you have, to how colleagues work and interact with you, to how you move up in an organization. But few of us are taught how to create great Wikis, excellent presentation decks, or craft thoughtful emails. We learn these skills by trial and error, if at all. If we're lucky, we may work for an employer that offers training on managing meetings effectively, writing professional emails, or putting together a slide deck. But in the absence of formal training, we have to find other ways to pick up these skills.

With that in mind, here are five ways software developers can improve their writing beyond personal blogging as well as resources for each:

1. Contribute to your team's internal documentation

Internal documentation in all its forms — videos, process documentation, post-mortems, incident reports, etc. — is critical in engineering team operations. We create these assets for numerous reasons, including for tracking work, onboarding, and communicating process changes. Few people peruse internal docs for fun, but creating them and maintaining them increases knowledge transfer within teams (this is critical when hiring new employees or when people leave) and ensures consistency across teams. Docs are a scalable way of recording how, and why, your team does things and sharing that across an organization.

Bonus points: Make sure you socialize the existence of your docs to external and internal stakeholders. If someone has a commonly asked question that is answered in your docs, point them to the right document. Documentation is only useful if people know it exists and if they know what they can find there. Help people find the answer to their problems by pointing them in the right place.

Resources:

2. Get paid to write and work with an editor

Plenty of tech companies have paid writer programs, where they accept externally contributed guides and tutorials and compensate the author for their work. Companies will typically pair a writer with an internal editor who will review the writer's work, provide feedback, and edit for grammar, syntax, and other style issues. Working with an editor is one of the best ways to improve your writing because you are getting detailed feedback. They are showing you what needs to be improved, how to improve it, and why.

Resources:

Tech Community Writing Programs List

3. Improve your code review process

Every team has its own norms and standards for how to conduct effective code reviews. But there are still ways to make your feedback clear, respectful, and easier to follow.

Resources:

4. Use templates for writing tech specs and reports

As is the case with code reviews, many teams have templates for their tech specs. But if yours doesn't, worry not — there are templates out there that can be tailored to your team's use case. Templates promote consistency (you're using the same format and including the same kinds of information and detail every time) while saving you time from recalling what to include. When I was in grad school, I had to write lots of reports. I looked for templates online for writing good usability reports and I found a template on Usability.gov that was so useful, I even adjusted it for reports I created at work. Today I have templates for everything from tech specs to how I format meeting notes to emails.

Resources:

5. Prioritize learning how to write better emails and chat messages

Many of us office workers went remote in 2020 due to COVID-19 and that meant more written messages. Email and chat are where a lot of interactions take place now and there are plenty of ways to get it wrong. In my 12-year career, I've never worked at a company that has given a "How to write good emails" class. I've learned it on my own. But if you want to be seen as effective at your job, reliable, trustworthy, and in general as a good colleague, make writing better emails a top priority moving forward. I recently released a 95-minute masterclass called "Writing Professional Emails" which shows you email features you must use, how to write emails in a variety of scenarios, and how to use email signatures, chat messages, and your work calendar to set boundaries. It's the email class you always wanted but haven't found – until now.

Resources:

Writing Professional Emails On-Demand Masterclass

In summary, personal blogging is one way software developers can extend their knowledge to others and improve their writing skills, but it's not the only way. Developers should also improve their business writing skills to help them establish a culture of knowledge sharing within their organizations.

This post originally appeared on my blog.

I'm Stephanie, a Content Strategist and Technical PM. Visit developersguidetocontent.com to learn more about my work!

How often do you update your personal website?👀

Stephanie Morillo — Thu, 17 Dec 2020 15:07:52 +0000

In today's discuss, I'd like to know:

How often do you update your personal website?
What types of updates do you make most often?

I update my website typically once or twice a month, and that is usually for publishing blog posts. However this month I've been conducting a huge SEO and content audit of my site and have made multiple changes. 😅 They're mostly content changes but there have been some design changes as well.

Share your updates in the comments!

How did you do this year with content creation?

Stephanie Morillo — Thu, 10 Dec 2020 16:36:39 +0000

Hi all! With the end of 2020 just a few weeks away, I've started doing my end-of-year reviews.

My questions to you all: how did you do this year with content creation, and what do you plan on doing differently next year?

An Introduction to Web Analytics

Stephanie Morillo — Tue, 24 Nov 2020 14:46:00 +0000

If you’re a developer running your own site, or you have a blog hosted on a blogging platform, you’re probably aware of web analytics. Content publishers rely on web analytics to understand how audiences are engaging with their content and to spot trends or patterns that will help them improve baseline metrics. For the purposes of this post, we’ll define web analytics and metrics as follows:

Web (or site) analytics: the collection, analysis, and reporting of data compiled from a website for the purpose of research and optimization.
Metrics: something that you want to measure, often (but not always) correlated with an action a user takes on the site or a page. Well known metrics include “page views”, “unique visits”, and “click-through rate”. While the definitions of these metrics are more or less the same across web analytics tools and services, the way they’re calculated depends on the platform in question.

If you’re unsure about what web analytics are or what metrics you should pay attention to, this post is for you. Resources for additional reading will be available at the end of this post.

Use Questions to Guide How You Look at Web Analytics

What makes web analytics useful is its ability to help you optimize your site and content strategy. Without these questions, analytics are an otherwise nice-to-have feature that you might not use. Analytics are only as reliable as the questions you ask and taking action based on your findings.

I only care about the data in aggregate, meaning, I look at what my total visitors do, not what an individual user did or did not do. I don’t run ads, I don’t retarget users on different platforms, and I don’t personalize my site content. I segment users in my email marketing platform in order to send relevant newsletters to specific subscribers and to archive inactive subscribers.

Here are some questions I look to my web analytics to answer:

What keywords are people using to find my content in organic search?
How do people find my blog?
After reading a post, where on my site do people go to next?
What are the biggest entry points on my site?
What types of content perform the best?
Which pages are underperforming?
How many people are opening my newsletters?
Which links in my newsletters receive the most clicks?
Are there trends or patterns among these links that I should be aware of?

Start crafting questions or problem statements to help you maximize the value of your web analytics.

What Web Analytics Can & Can’t Tell You

As a content creator, web analytics is a tool that will help you gauge how well your content is performing. Web analytics can tell you what users do when they land on your post, what they do next, and how they get there. You can use this information to optimize your content calendar for high-performing topics, or to improve your search engine optimization strategy if you notice you get little traffic coming from search engines.

Web analytics cannot tell you why a user took a certain path, why a bounce rate is so high, or why a blog post performed lower than expected. You can infer by looking at the data over time and identify patterns of behavior, by formulating a hypothesis based on what you see and running an experiment (A/B test), or by conducting user research like usability testing and user interviews.

Also – different platforms may only analyze a portion of the available data, especially if you’re using it for free (Google Analytics does this for sites using its free version) or paying for a premium service but by tier (Matomo Analytics prices its plans according to a monthly visitor cap). Blogging platforms that have their own native web analytics may give you only a limited set of metrics to look at; for example, Hashnode and DEV Community will show you total pageviews, number of comments, and number of “reactions”, i.e. likes, but that’s it.

Cookies (otherwise known as HTML cookies or site cookies) impact the data your analytics tools are able to collect. If you use persistent cookies, you may be required to display a cookie banner on your site (there are exceptions; look at your web analytics provider for more details). Also, blogs hosted on platforms like Hashnode and DEV Community are governed by the platform’s cookie compliance policies). Users may have “do not track” settings enabled, and whenever a user clears their cache, they’re treated as a unique visitor the next time they visit your site. These aren’t things to lose sleep over but important to keep in mind.

Types of Metrics and User Data

Web analytics tools also calculate metrics. Here are some common metrics by analytics tool (this is not an exhaustive list):

Web analytics metrics:

Total & unique visits
Total & unique page views
New vs returning visitors
Traffic sources
Bounce rate
Exit rate
Click-through rate
Time on page

Social media analytics metrics:

Total number of impressions
Number of likes
Number of comments
Number of retweets/reposts

Email marketing metrics:

Total number of recipients
Number of opens
Open rate
Number of clicks
Click-through rate

You can also add your own metrics to these platforms; many companies have metrics that correspond with different funnels and will make sure their analytics includes all the metrics they need to track.

How about user data? If you’re using a robust analytics platform, you’ll be able to view the following user data:

Referral sources: the places where users come from and drive traffic to your site
Device type
Operating system
Country: where users are located
Region
Browser language

This data might be way more than you need at this point. But this type of data forms the basis of segmentation. Segmentation is the grouping of audiences by specific characteristics. If you want to run A/B tests for specific subsets of users, or if you want to focus on improving your site’s UX for certain device types, this type of data will help you target the right users

How Web Analytics Platforms Get Data

In general, most web analytics platforms will require you to embed a tracking code (usually JavaScript) to your site’s header or footer. The code will execute on each page on the site. This lets your web analytics capture “events” on each page, or actions your users do like clicking a link, a page, the time they spend on a page, and so forth. Your web analytics platform logs the data and will often display data as visualizations in a dashboard. Most platforms have default dashboards but you can also create custom dashboards and reports from within your tool.

Furthermore, web analytics platforms drop cookies in a user’s browser to track them on the site during their current visit (these are called “session” cookies) or to remember them in subsequent visits and/or track their movements beyond the site for advertising purposes (these are called “persistent” cookies). Analytics uses session vs persistent cookies to differentiate between total visits and unique visits, which count only the first time you visited the site. Note: cookies don't track users across devices, so the same user accessing the same page on both their mobile phone and their laptop would count as two unique visits.

Other Uses of Web Analytics

Because of the mechanisms used to collect data, web analytics platforms also power the following types of activities:

Retargeting. If you’ve seen an ad on a news website for a product you shopped for on a different site, this is retargeting in action.
A/B testing. Online experiments, or A/B tests, work by serving up a variation of a page that has had a small change made to it. Visitors are randomly assigned to either the “control” group or the “treatment” group; the control group sees the existing experience and the treatment sees the change. On the backend, the analytics platform measures any changes to key metrics on the page and uses statistics to determine which version is the winner.
Personalization. Personalization works by serving a different version of a page to a group, or “segment” of users, based on shared characteristics. These segments are built based on the activity previous site visitors have done and will “serve” them an experience based on which segment they fall into.

These activities may require a separate system to run, but they use web analytics as their data source.

Which Web Analytics Tool to Use

Google Analytics by far is the most popular web analytics platform for everything from personal sites to large, enterprise sites. It’s free to use, but with everything, there’s a catch: GA will only analyze a portion of your data, and user data is sent to and hosted on Google servers. If this is an issue, consider other analytics tools. When looking for an analytics platform, I was looking for one that was robust, that didn’t share data with third parties, and that was privacy-minded. Here are some platforms that are similar (some are even open source):

Matomo Analytics
Fathom Analytics
Simple Analytics
Plausible Analytics

Note that there’s nothing wrong with only having access to a slice of your metrics and data. For some people, platforms like Matomo and Google Analytics are too rich and tell them more about their users than they need or want to know. As long as you understand what metrics are valuable to you and what you can and can’t infer from these metrics, use the platform that is right for your use case.

I would recommend reading up on all of these options (and there are many more) to find the one that meets your needs.

Conclusion

Web analytics tools work by collecting data on the actions users take on your site in order to improve your site’s usability, content, or to create personalized experiences. To use them for data-driven decision-making, craft questions that align with your metrics and look at your analytics regularly to spot changes in metrics. Finally, research the differences between analytics tools to identify the best one for you.

Resources

This post originally appeared on my blog.

I'm Stephanie, a Content Strategist and Technical PM. Visit developersguidetocontent.com to learn more about my work!

Have you made recent changes to your workflow to boost productivity?

Stephanie Morillo — Tue, 03 Nov 2020 15:14:42 +0000

Hi all,

I'm curious: have you made recent changes to your workflow to boost productivity? And if so, what are they?

Lately I've been using Zapier a LOT more heavily to help me manage my daily life (my attention is split between home improvement projects, my side business, and my day job).

Kurt Kemple wrote an excellent article about using Zapier to automate parts of your workflow.

What have you changed and why?

7 Pieces of Information to Include in Technical Blog Posts

Stephanie Morillo — Fri, 09 Oct 2020 14:55:40 +0000

[Image: #WOCinTech Chat]

This weekend I asked Twitter, “What are some of your pet peeves when it comes to technical blog posts?”

What I really wanted to know was, “What’s missing in technical blog posts?” I get asked what information technical blog posts should include and how should posts be structured. As a reader of technical content myself, I sometimes only realize what’s missing once I’m reading it. I wondered if others were able to identify pieces of information that they need in a blog and why. (I received 22 responses; thank you to everyone who shared their thoughts in the thread!)

In this post, I will share seven crucial pieces of information that should be included in technical blog posts based on feedback from developers on Twitter:

1. Text that introduces and contextualizes a code snippet

Text that precedes a code snippet properly orients a reader. Without any context or instructions, a reader may feel like they have missed a step and may not understand how the author arrived at what’s being presented. Without explicit information, readers will wonder the following:

What am I looking at?
Is this a command line or a file?
Am I supposed to type this in somewhere, or is this output from something else?
What’s the expected output/behavior?
I’m seeing an error when I type this. Am I supposed to get an error?

How do we write good code snippets? DigitalOcean’s writing guidelines contain a section called “Commands and Code in Steps” which includes examples of how to format commands and code snippets, and how to introduce them. Redux maintainer Mark Erikson also recommends including the path and file name at the top of a file.

2. Code snippets as text

While some blogs allow authors to preserve the formatting of code blocks, others don’t. Authors circumvent this by pasting code snippets as screenshots, but there’s one problem: screenshots aren’t accessible with screen readers. Not only is the code in the image inaccessible, but authors don’t consistently add alt text to their images.

To make it accessible, host the code snippet elsewhere (a GitHub repo or gist, for example) and add a link to the code snippet in the image caption for quick reference.

3. Alt text to all images, screenshots, and diagrams

Continuing with accessibility, alt text is an HTML attribute where authors can place descriptions on their images. When screen readers find an image on a page, they will read whatever description is provided in the alt text. Without this, a screen reader cannot interpret what the image is.

Earlier this year, I suggested adding code snippets to alt text. But Eric Eggert recommends hosting the code snippet elsewhere and not putting the code snippet in the alt text. Still, do add a basic description of the code snippet in the alt text for screen readers in addition to linking out to the snippet.

4. Final results of the tutorial’s code

What is everything supposed to look like at the end? Software engineer Thalida Noel recommends adding the final results of the code referenced in a tutorial blog post in order to “[see] how all the pieces fit together to determine if this is how I want to implement.”

5. Prerequisites including a list of dependencies and libraries

Prerequisites are a list of things that readers need to know, have, or do before reading your blog post. In a recipe, for example, it would be a list of ingredients and equipment, and maybe some pre-work that needs to be done. In a technical blog post, the prerequisites should list what prior knowledge or experience readers need with a topic and all the dependencies and libraries that need to be installed in order to follow code snippets. (Jacque Schrag says she has seen dependencies references in the body of a blog post, but not in the prerequisites.)

6. Release versions

Most technical tutorials have a shelf life because of software versioning. Including release versions in a blog post help readers find that information more easily; maybe they’re searching for a blog post that uses Ruby 2.2.6 and not Ruby 2.3. Developer Jorge Vergara lists the release versions as metadata at the top of his blog posts.

7. Publish date

A blog post publish date (or “last updated” date) is an important piece of metadata that communicates how current the examples in a blog post are, as @marmalade points out. Without this, readers don’t know if they’re reading something that is outdated (see #6 above). Include the original publish date and, if the post was updated, include the “Last updated” date as well to indicate the information is current.

While not comprehensive, including these seven pieces of information will help you anticipate questions readers may have when they visit your blog post.

Resources:

This post originally appeared on my blog

I'm Stephanie, a Content Strategist and Technical PM. Visit developersguidetocontent.com to learn more about my work!

Why did you decide to pursue a career in tech?

Stephanie Morillo — Tue, 29 Sep 2020 17:43:58 +0000

Hi everyone 👋🏽—

I've been in tech eight years and one thing is abundantly clear: everyone has a story as to why they're now in a tech career.

Whether you come from a non-traditional background or majored in Computer Science (or another computing discipline), why did you decide to pursue a career in tech? What do you like most about being in tech?