Best Practices

Optional guidance and recommendations about organizing, authoring, and managing your technical documentation.

1: Hugo Content Tips
2: Organizing Your Content

Use this section to learn about some of the best practices around creating technical documentation with Docsy.

1 - Hugo Content Tips

Tips for authoring content for your Docsy-themed Hugo site.

Docsy is a theme for the Hugo static site generator. If you’re not already familiar with Hugo this page provides some useful tips and potential gotchas for adding and editing content for your site. Feel free to add your own!

Linking

By default, regular relative URLs in links are left unchanged by Hugo (they’re still relative links in your site’s generated HTML), hence some hardcoded relative links like [relative cross-link](../../peer-folder/sub-file.md) might behave unexpectedly compared to how they work on your local file system. You may find it helpful to use some of Hugo’s built-in link shortcodes to avoid broken links in your generated site. For example a {{< ref "filename.md" >}} link in Hugo will actually find and automatically link to your file named filename.md.

Note, however, that ref and relref links don’t work with _index or index files (for example, this site’s content landing page): you’ll need to use regular Markdown links to section landing or other index pages. Specify these links relative to the site’s root URL, for example: /docs/adding-content/.

Learn more about linking.

2 - Organizing Your Content

Optional guidance and recommendations on how to organize your documentation site.

If you have a look at our Example Site, you’ll see that we’ve organized the Documentation section into a number of subsections, each with some recommendations about what you might put in that section.

Do I need to use this structure?

Absolutely not! The site structure in the Example Site was created to meet the needs of large docsets for large products with lots of features, potential tasks, and reference elements. For a simpler docset (like this one!), it’s fine to just structure your docs around specific features that your users need to know about. Even for larger documentation sets, you may find that the structure isn’t useful “as is”, or that you don’t need to use all the section types.

We do recommend that (as we’ve done here) you provide at least:

An Overview of the product (either on the docs landing page or a separate Overview page) that tells the user why they should be interested in your project.
A Getting Started page.
Some Examples.

You may also want to create some tasks/how-tos for your project’s features. Feel free to copy this Docsy user guide site or even just the docs section instead if you like this simpler structure better.

Tip

If you want to copy this guide, be aware that its source files are inside the Docsy theme repo, and so it doesn’t have its own themes/ directory: instead, we run hugo server --themesDir ../.. to use Docsy from its parent directory. You may want to either copy the site and add a themes/ directory with Docsy, or just copy the docs/ folder into your existing site’s content root.

Learn more about how Hugo and Docsy use folders and other files to organize your site.

Why this structure?

We based the Example Site structure on our own experiences creating (and using) large documentation sets for different types of project and on user research carried out on some of our bigger sites. In user studies we saw that users cared most about and immediately looked for a Get Started or Getting Started section (so they could, well, get started), and some examples to explore and copy, so we made those into prominent top-level doc sections in our site. Users also wanted to find “recipes” that they could easily look up to perform specific tasks and put together to create their own applications or projects, so we suggest that you add this kind of content as Tasks. Other content types such as conceptual docs, reference docs, and end-to-end tutorials are less important for all doc sets, particularly for smaller projects. We emphasize in our Example Site that these sections are optional.

We hope to improve the Example Site structure further as we learn more about how users interact with technical documentation, particularly for Open Source projects.

Writing style guide

This guide and the example site just address how to organize your documentation content into pages and sections. For some guidance on how to organize and write the content in each page, we recommend the Google Developer Documentation Style Guide, particularly the Style Guide Highlights.