Photo by Pritesh Sudra on Unsplash

Imagine if you could have a “flight” of docs sites to have a docs site tasting party! The docs aficionado in me wants to go to such a party. What would be served? How about a taste of Sphinx, Astro, Hugo, and Jekyll, with a final taste of Mkdocs and Docusaurus? Let’s have fun with it (even if the metaphor breaks down quickly).

Sphinx: The Rich Espresso for Documentation

Sphinx is a powerful documentation generator initially created for Python projects. It excels at producing structured, text-heavy documentation emphasizing cross-referencing and indexing. Using reStructuredText as its markup language, Sphinx offers robust extensibility through various plugins and themes. Many technical documentation teams appreciate its ability to generate outputs in multiple formats, including HTML and PDF. However, its complexity can be daunting for newcomers unfamiliar with its syntax or configuration.

Astro: The Sparkling Citrus Spritz of Static Sites

Astro is a modern static site generator designed for speed and flexibility. Unlike traditional SSGs, Astro allows developers to mix and match different frontend frameworks like React, Vue, and Svelte while focusing on shipping minimal JavaScript to the browser. This approach makes Astro an excellent choice for performance-conscious documentation sites. With its component-driven architecture, Astro enables content creators to build engaging doc experiences while maintaining simplicity in content management.

Hugo: The Smooth Bourbon of Speedy Site Generation

Hugo is one of the fastest static site generators available, and it is known for its speed and efficiency. Written in Go, Hugo boasts nearly instant build times, making it a favorite among developers who need quick iterations. It uses Markdown for content and has a powerful and flexible templating system. Hugo is ideal for large-scale documentation sites, thanks to its excellent support for taxonomies, multilingual content, and customizable themes. However, the learning curve can be steep for those unfamiliar with its templating language.

Jekyll: The Classic Red Wine of Static Sites

Jekyll is a well-established static site generator that powers GitHub Pages, making it a popular choice for open-source projects. Built with Ruby, Jekyll processes Markdown files and converts them into static HTML. Its simplicity and deep integration with GitHub make it an appealing option for developers looking for an easy way to deploy documentation. While Jekyll offers plugins and themes, its speed and flexibility may not match newer SSGs like Hugo or Astro. Still, it remains a reliable choice for lightweight and version-controlled docs sites.

MkDocs: The Refreshing Iced Tea of Documentation

MkDocs is a straightforward static site generator designed explicitly for documentation projects. It prioritizes ease of use with a simple configuration file and Markdown-based content. MkDocs includes a built-in live preview server, making it easy to see changes as you write. One of its most popular themes, Material for MkDocs, enhances the experience with modern styling and extra features. While MkDocs may not be as extensible as Sphinx, it is an excellent choice for teams looking for a quick, efficient way to publish documentation.

Docusaurus: The Trendy Matcha Latte of Docs

Docusaurus, developed by Facebook, is a React-based static site generator optimized for documentation sites. It provides out-of-the-box support for versioning, internationalization, and a structured navigation system. Docusaurus embraces a modern development approach, allowing developers to leverage React components for interactive documentation. Its ecosystem includes a vibrant community and a growing number of plugins. While its reliance on JavaScript may be a drawback for those seeking pure static solutions, Docusaurus remains a top contender for teams wanting a dynamic, developer-friendly documentation site.

Feel free to quiz an author, Anne Gentle, and share any quirky test results by using the Contact form.

Are you curious? It’s free and crafted with the latest ChatGPT 4. Signing up for a (free) OpenAI account is required. I would love to hear what you think if you’re willing to try it out.

Ask Anne Gentle about treating docs like code

This chatbot is aware of the revision to the third edition of Docs Like Code: Collaborate and Automate to Improve Technical Documentation.

Discover the Latest Edition of Docs Like Code: Available Now

One of the most exciting updates to Docs Like Code describes how to eliminate biased language. The tools are ready: you can encode inclusive language policies for linters such as Alex or Woke. Most recently, you can learn with a brief demonstration on using a CODEOWNERS file to govern who can publish the docs in a given repository.

Mirantis: Can you please introduce yourself?

Anne Gentle: I work on OpenStack documentation full time at Rackspace, and I actually was the second hire Rackspace did for the OpenStack project. It was the greatest match I could ever wish for. I wrote a book in 2009 about how to do community collaborative documentation, and I had volunteered a lot with open source docs projects. This job showed up in my backyard in Austin, Texas, and I just jumped at it.

Q: What is the major difference between open source and closed source documentation?

A: The first big difference is interest in open-ness everywhere, from authoring to publishing to display. I was even asked if all of our fonts are open source in the first few weeks I started! Our toolchain is open to anyone to author with or tinker and re-use themselves. The second difference is in licensing. In a closed source environment, the documentation is very legally bound to provide a certain service-level or billing agreement. The idea behind open collaborative docs is that anyone can edit them and, in some communities, the ethos is very involved in the attribution of content. That’s a really good case for creative commons licenses.

So there’s a whole range, but a lot of it is around licensing and the freedom of the content, I also believe there’s a lot of interesting innovation going on in open source. For many of the same reasons you would do open source coding, I think there’s a similar draw for open source docs.

Q: What makes open source documentation so special?

A: There is a need to have a lot of discipline around documentation, and open source surprisingly lends itself to that. Open source, especially projects that try to tie docs to code as much as possible, are actually going to be very disciplined in their processes. Read more…

Here’s a brief overview of two additional types of rendering:

1. 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 HTML rather than generate it on the fly. Pre-rendering can significantly improve the speed and performance of a website, as it eliminates the delay caused by rendering the page on the server.
2. Progressive rendering: Progressive rendering, on the other hand, involves generating and serving the HTML, CSS, and JavaScript for a website in stages as the user requests the page. For example, the server might first serve a basic HTML page with minimal styling and functionality and then progressively add more content and features as the user interacts with the page. Progressive rendering can help reduce a website’s initial load time, as the user can start interacting with the page before all the content and features are loaded.

When evaluating a Static Site Generator (SSG) it’s best to understand the performance requirements for your docs site on both the amount of content you need to render immediately and that which can wait in the user’s browser. In the case of NextJS and Gatsby, once the app’s JavaScript is loaded to the client’s browser, JavaScript code picks up the work, but initially, a pre-rendered initial static HTML is available for reading. NextJS and Gatsby are built on the base React frontend framework.

Considerations for SSGs and technical documentation

In summary, pre-rendering involves generating the entire website at build time, while progressive rendering involves developing and serving the website in stages as the user interacts with it. Both techniques can help improve a website’s performance and user experience, but they have different strengths and use cases. Pre-rendering is best suited for websites with a lot of content and features that can be generated beforehand. In contrast, progressive rendering is best suited for websites that need to load quickly and allow the user to start interacting with the page as soon as possible. Pre-rendering is likely best for most documentation sites. Documentation built into a dashboard may benefit from tight integration and progressive rendering. Like the considerations when Evaluating print, PDF, or epub output, or evaluating themes, you want to evaluate rendering when looking into static site generators.

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

1. 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 collaborating with other writers or contributors.
2. Collaboration: GitHub makes collaborating with other writers, developers, engineers, technical reviewers, and editors easy. You can create branches for different sections of your documentation and merge changes back into the main branch when they are ready.
3. Hosting: GitHub provides free hosting for your documentation, making it easy to share your work with others. You can also customize the look and feel of your documentation using templates and themes.
4. Automation: GitHub has built-in tools for automating tasks like building and deploying your documentation. This can save you time and help ensure your documentation is always up-to-date.

Getting Started with GitHub for technical writing

1. Set up a Development Environment: If you want to build locally, you need to be ready with the prerequisites for the Static Site Generator of your choice: Python/Sphinx, Ruby/Jekyll, or Go/Hugo.
2. Create a Repository: To get started, create a new repository on GitHub for your documentation. Depending on your needs, you can make it public or private.
3. Choose a Markup Language: GitHub supports a variety of tools for creating documentation, including Markdown, reStructuredText, and AsciiDoc. Choose the one that works best for you.
4. Write and Collaborate: Start writing your documentation and collaborate with others using branches, pull requests, and comments. Remember to use clear and concise language and logically organize your content.
5. Publish and Automate: Once your documentation is ready, publish it using GitHub Pages. You can also set up automation using GitHub Actions to build and deploy your documentation automatically.

Hopefully, you see that GitHub is a powerful tool for technical writers, providing version control, collaboration, hosting, and automation features. Following these tips, you can use GitHub to create and manage your documentation today. Or tomorrow if that fits your schedule better.

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 makes it popular for creating articles, comments, replies, blog posts, and other essential content like documentation. Learn more about GitHub for Documentation on the docsascode.com site.

Asciidoc is a more powerful markup language designed for more complex content. Asciidoc uses a more extensive syntax than Markdown, allowing you to create more advanced formatting elements such as tables, footnotes, and cross-references. Asciidoc is also designed to be extensible, allowing you to create custom markup elements to suit your needs. Extensibility makes it ideal for creating technical documentation, ebooks, and other complex content.

You may find that Markdown is simpler and easier to learn; you can also see that Asciidoc is more powerful and flexible. If you only need to create basic content, Markdown is a great choice. However, if you need to create more complex content with advanced formatting and custom markup elements, Asciidoc is the better choice.

In conclusion, Markdown and Asciidoc are functional markup languages for creating and formatting digital content. While Markdown is simpler and easier to use, Asciidoc is more powerful and flexible. Ultimately, the choice between the two depends on the specific needs of your project. If you’re unsure which to choose, start with Markdown and work up to Asciidoc when you need more advanced features.

1. 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. Look for projects with active documentation efforts that could benefit from your technical writing skills. You can find open-source projects on sites like GitHub, GitLab, or Bitbucket.
2. Get to know the community: Before getting started, take some time to get to know the community surrounding the project. Read through the project’s documentation and code, and look at any issue trackers or forums where discussions occur. This will help you understand the project’s goals and how you can contribute. Look at some Trends and Open Source Writing.
3. Identify areas where you can contribute: Once you’ve identified a project and gotten to know a few community members, look for places to contribute. This might include updating existing documentation, creating new documentation, or working with developers to improve the documentation workflow. Consider starting with small contributions, like fixing typos or clarifying confusing documentation sections, before tackling more significant tasks.
4. Learn the tools and technologies: To contribute to a docs-as-code project, you’ll need to be familiar with the tools and technologies developers use. This includes version control systems like Git, markup languages like Markdown, and static site generators like Jekyll or Hugo. Take time to learn these tools and technologies, or contact the community for guidance. The DocsLikeCode.com/Learn area has tutorials to get you started.
5. Engage with the community: As you work on the project, engage with the community by participating in discussions and sharing your work. Be open to feedback and willing to make changes based on input from others. This will help you build relationships with other contributors and better understand the project. I’ve got another article, How to Build OpenStack Docs and Contributors through Community, that may help. We even held an OpenStack Docs Boot Camp one year to get to know each other.
6. Highlight your contributions: Finally, highlight your contributions to the project on your resume and in future job applications. Potential employers look at your contributions to open source and your experience working in a docs-as-code environment.

I’ve found that volunteering in open source can be an excellent way for technical writers to learn docs-as-code and gain experience working with other professionals in the field. By following some of these suggestions, you’ll be well on your way to building a successful career in technical writing. Be sure to check out Google Season of Docs if you’d like to participate in a structured way.

Their billboards feature witty and humorous sayings that play on their reputation. For example, one billboard reads, “Restrooms you have to pee to believe,” while another says, “You can’t buy happiness, but you can buy Beaver Nuggets, and that’s kind of the same thing.” These billboards are memorable, entertaining, and effective at driving traffic to Buc-ee’s stores.

I look at these sayings and think, “Content strategy doesn’t have to be boring – you can have fun with your content strategy!”

Even in tech writing, you can use social media and community posts with your content strategy for fun. Take advantage of trending hashtags or memes and create a version that’s relevant to your brand. For example, if there’s a popular meme format, you could make your own version promoting your product or service.

Our teams have been playing around with this at Cisco with a Meme Monday and a Fun Friday. Another fun content strategy is to create quizzes or polls that tap into your audience’s interests. For example, if you’re a doc writer for an AI service, you could create a quiz that helps people determine their prompt personality or a poll that asks them to vote on their favorite training models. These types of interactive content not only engage your audience but also provide valuable insights into their preferences.

To summarize, a clever content strategy shouldn’t be all serious and boring. Injecting humor and entertainment into your tech writing efforts can make them more memorable and effective. Take inspiration from Buc-ee’s billboards, create quizzes or polls, and leverage community trends to add fun to your content strategy.

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. In December 2023, I made another set of changes to demonstrate how to use a CODEOWNERS file to govern who can publish the docs.

While researching, it became apparent how much larger the docs sites are, such as Read the Docs serving 55 million pages a month; wow! And many more teams and organizations have adopted these techniques, so the updates incorporate those examples.

Plus, pricing for the related tools has changed and, in some cases, has decreased per month, providing additional value. There are even open-source rulesets for the Microsoft or Google Style Guides available for free, which you can enable as tests in a CICD pipeline. You can find more contributing guides in addition to those style guides. Enabling contributors on Windows is easier than ever since you can use it for a development environment and a docs-as-code system.

How to Get the Third Edition of Docs Like Code?

You can buy either a printed copy or an ebook from these online sellers:

Lulu printed paperback | Lulu ebook

Amazon printed paperback | Amazon ebook

What are people saying about the Third Edition of Docs Like Code?

“I found it very insightful, and (as a “former” developer) relatable. I think there is a lot of value to many organizations, particularly large/enterprise settings.” – Rob Montalvo, Co-Founder and President, DataCrunch Lab

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.

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.

Reaching out to current contacts

First, I reached out to Andy Oram, a senior editor at O’Reilly who knows me from a couple of open source projects, asking if he thought O’Reilly would want a book proposal. He said he’d be happy to read what I had but didn’t see the initial concept fitting into their current catalog. Really great of him to offer to help out, and I simply thanked him and kept going with my idea.

In parallel, I reached out to the publisher for my first book, Conversation and Community. His name is Richard Hamilton and he runs XML Press. When he looked at his schedule, he couldn’t read through at the draft copy for about 3 months. Well, I thought that the timing was essential, and I didn’t want to wait that long, knowing both the market and my own availability.

Finding like-minded collaborators

I also reached out to Diane Fleming, now Skwish, who had been teaching writers how to use Git and GitHub for docs over the same time as I had been. Over lunch, we realized we both wanted this book to be available for the next time we teach developers and writers how to write and review docs on GitHub. Diane is a talented writer and also a super editor. The best writers re-write a lot, and I knew Diane would provide an eagle eye for both technical accuracies as well as great writing.

Then, I realized I have a great friend in Kelly Holcomb, who edited my first book and I could talk her into editing this one, wahoo! Kelly also had experience in using GitHub for editing, so her contributions were super important for the final copy.

One area I did skip for this book was a professional-level index, which Kelly was able to do a great job on for Conversation and Community. I haven’t missed the index yet, and for a smaller book, it seems like an index could look like padding.

Design materials and promotional work

I also was able to do all the design imagery myself, including the book cover. This part was thanks to Canva and some nice templates that the service has online. I used the free trial for Canva to make the book cover and stickers and t-shirt design.

That said, I was not willing to take on the layout work myself. So, when Gitbook did not output a PDF that I considered “print-ready”, I went to Upwork. Upwork let me hire a professional layout designer who could create a fine-tuned layout and design for the print copy, including proper page breaks and nice tables. I hired a designer with access to Indesign who could take the epub file and turn it into a print book.

Pull it together!

And so, with all those bits of input from others, it created a quest to be a product manager for my own information product! I went that route, and for me, Lulu was a tool I was already familiar with because we had done publishing with it for OpenStack.

There are other publishing options – IngramSpark, Amazon, LeanPub, and I’m sure others. I did sign up and get approved for an account with IngramSpark, which is the print-on-demand service that XML Press uses.

To me, after reading the origin story for Lulu, I feel that Lulu is a bit more “open source” based than say, Amazon. I don’t know much about LeanPub. Since I was using Markdown on a private GitHub repo anyway, it doesn’t seem to offer more than Lulu for the marketplace reach. I’m not trying to make money at it; only trying to increase reach.

Finding a freelance editor would be a huge leg up on the writing process itself, especially if you also need a bit of developmental editing for the book idea.

For the print layout, I had a great experience with UpWork and was also able to keep the same person for the work I needed for the second edition. I learned from using a freelance site that I can find and manage freelancers for projects that I want to get done but don’t want to carve out time or buy tools for myself to finish.

List of tools and services

Ongoing and startup costs

Here’s a high-level overview of the startup costs for creating a book like Docs Like Code. I calculated the starting costs for six or five months when I needed a monthly subscription for a service.

Based on Lulu reporting, I see the book brought in about $2500 in 12 months of the first and second editions being available. So while the startup costs are something, I did see a profit from the effort. Really, though, the effort is paid off in helping others see the benefits I’ve observed and in sharing and learning. Let me know what you think about this method, the tools, and of course, the resulting book, Docs Like Code, which you can buy online.

First published on Docs Like Code at https://www.docslikecode.com/articles/practical-advice/ in April 2018.

An update for June 2022

Ongoing costs continue, though the costs have not increased. I have switched from GitHub Pages to Netlify for the website for the book, but that service continues to be free. GitHub monthly costs have gone down to $4/month. I have paid for Canva over time as it turns out to be a very useful service for many other purposes. I stopped selling t-shirts a few years ago, and no longer print stickers. So those are both rare if you still have them! I no longer pay for GitBooks service since I can build it locally and don’t need hosting or collaboration features from that service.