Pre-rendering and progressive rendering are two techniques used by static site generators to improve website performance and user experience. Rendering is generating HTML. In the case of Static Site Generators, this is not the same as web page rendering as explained by Constructing the Object Model on the web.dev site. Here’s a brief overview of two additional types of rendering: Pre-rendering: Pre-rendering involves generating the HTML, CSS, and JavaScript for a website at build time before the user requests the page. When a user visits the website, the server can serve the pre-rendered HTM ..read more

GitHub is a popular platform for software developers to manage their code repositories, collaborate on projects, and track changes over time. However, it is also a powerful tool for technical writers to create and manage documentation. In this blog post, we’ll explore the benefits of using GitHub for technical writing and share some tips for getting started. Benefits of Using GitHub for technical writing Version Control: With GitHub, you can track changes to your documentation over time, allowing you to revert to previous versions or see who made what changes. This is especially useful when c ..read more

You can use either Markdown or Asciidoc for creating and formatting digital content. While both languages serve a similar purpose, they have distinct differences that suit them for different use cases. Let’s explore the use cases for each markup language so you can make the best choice. Markdown is a simple markup language that is easy to learn and use. It uses a simple syntax to create headings, lists, links, and other essential formatting elements. GitHub, Reddit, and Stack Overflow all support Markdown in their platforms, making it ubiquitous outside of technical writing. This ubiquity make ..read more

As a technical writer interested in learning docs-as-code, volunteering in open source can be a great way to gain experience and develop your skills. It’s a path I took early in my career; I learned what I wanted to know by volunteering in open source. You can take the opportunity to work with other professionals in the field, and you’ll also be contributing to a project that benefits the broader community. Here are some tips on how to get started: Choose a project that interests you: The first step in volunteering in open source is to find a project that aligns with your interests and skills ..read more

I used to drive up and down I-35 to get to my job (in a reclaimed mall) at Rackspace in San Antonio. I passed by Buc-ee’s and their billboards many times on that drive. Buc-ee’s is a super-charged truck stop based in Texas, with a large selection of just about anything (clothes, snacks, candy, jerky) and some of the self-proclaimed best restrooms in America. It’s hard to imagine until the sliding glass doors glide open, and you stand in awe of the size and scope of such a place. Here’s their interesting content strategy, though; they have a straightforward website, but the copywriting on their ..read more

Five years have passed since the last update to the Docs Like Code book. This time the book has earned a new subtitle: Collaborate and Automate to Improve Technical Documentation. If you’ve already read the book, please spread the word! Send a Tweet or post on LinkedIn. What’s Updated in Docs Like Code? One of the most exciting updates describes how to eliminate biased language. The tools are ready: you can encode inclusive language policies for linters such as alex or woke. While researching, it became apparent how much larger the docs sites are, such as Read the Docs serving 55 million page ..read more

What does it take to put together a website, a book, an ebook, all for sale online? Let’s look at costs for tools and services that make it happen. Let’s look at what you need for a book idea. You need an audience, an editor, a way to reach that audience, and a “pitch” for the book idea itself. You may choose self-publishing over pitching the book idea to a technical book publisher. Photo by Pixabay on Pexels.com In my recent experience with Docs Like Code, the process led me to choose to produce the site, epub, and printed book all using tools I had prior experiences with. Let’s take a look ..read more

You may find that the free plan gives you all you need, but for four dollars a month, access to Codespaces, Pages, and Wikis are right in the sweet spot for technical writers using GitHub and docs-as-code techniques. Summary of GitHub Team plan benefitsWhat has changed in GitHub pricing? I previously wrote GitHub Pro Account Or GitHub Free Account For Technical Writing when the plans were $8 USD per month, and you needed to pay that level to have access to private repositories and to work with other collaborators privately. Now the paid “Team” plan gives you many more benefits than just access ..read more

When using docs-as-code techniques, writers might hesitate to work with others on content deliverables, and developers might feel they have little to contribute to the documentation. I assert is that no one can know everything, so distribute the workload by writing together just like you collaborate together on code. What about reviews? How do you maintain quality while working on documentation in a code repository? Here are some ideas. GitHub Inline Reviews for Documentation In GitHub, you send in Pull Requests, which are changes to the files so that you can see the differ ..read more

Versions of software product or a service need documentation sites to match those version numbers. As I investigated and learned more, I found layers of complexity when using a source control system to version the source documents while outputting a nice user experience with a static site generator such as Jekyll. I have one possible solution to try out in this repo: https://github.com/justwriteclick/versions-jekyll/. Give it a try! The post How to create a versioned docs site with Jekyll first appeared on Just Write Click ..read more