You can build a documentation site without spending valuable resources like dev hours.
Usually, doc sites are built by developers, but there are many applications to create a public support website or knowledge base for clients. From open source to commercial, or no-code to "I need a developer to change this font." You can have it all.
So how can you make a documentation site when the dev team is not around or the timeline to build one is months away, and you needed it yesterday.
Truth be told, building a documentation site is not that different from making any other website, but I am going to assume some things before we dive into the details:
- you already have a domain name (if you want to use one);
- getting started quickly is more important than having total control;
- nontechnical authors/contributors will work on the documentation;
- you don't want a dev team to maintain and build the site.
Use the table of content to jump to any section of the article.
- Choose a documentation website builder
- What is Archbee, and why should you use it as a documentation platform?
- How to create a documentation site
- Take care of some essential settings
- Create the structure of the documentation website
- Adding content
- Use templates to produce content faster
- Import content from other sources
- Create a navigation menu with multiproduct or product versions
- Customize your website
- Craft a landing page
- Conclusion on how to make a documentation website
Choose a documentation website builder
There are many different types of documentation sites - from software documentation to project or policy documentation - but they all share some common traits. Here is what makes a docs site successful:
- supports multiple users;
- easy editing capabilities so that anybody can contribute;
- permission and access control;
- lightweight interface in terms and features and design;
- strong search functionality to find relevant information;
- fast loading times and SEO options;
- WYSIWYG interface rather than markup languages like Markdown.
Most of the time, a developer is involved in the process of choosing a documentation site generator, and they might recommend some open-source apps. Most of them require maintenance and development time for updates or deployment.
To overcome the shortcomings of open-source static sites generators, you can use a service that makes documentation site-building simple.
Any solution you will choose has some level of drawbacks, so before you build anything, plan accordingly. When selecting a documentation software vs. an in-house solution, analyze the options based on your use case.
If you go for an open-source documentation site generator, choose a well-known project. Here are some of them:
With Hugo, building docs site is swift, and it is growing in popularity. Great for a small site where the author has some technical skills. Down the line, it can also become a bottleneck when updating and deploying the site. On the other hand, Hugo has a robust community theme called Docsy dedicated to documentation sites.
Docusaurus is open-sourced and backed by Facebook and is dedicated to quickly building, deploying, and maintaining docs websites. The content is generated based on markdown files, so that's something that an author needs to know how to use.
Both options need to be maintained as they need to be hosted, need an SSL certificate, or updates to a new version.
No matter the tool, there is one thing when you choose a documentation site builder: the output should be in the form of a static site (more on this later).
What is Archbee, and why should you use it as a documentation platform?
If you skipped on the open-sourced solutions, your next option is to choose a documentation software.
Meet Archbee - a CMS and hosting platform for product, developer, and API docs and allows easy private or public access. Here are the main concepts you need to know about Archbee.
The content is grouped in collections. This is how you organize your documentation.
Each collection has a document tree hierarchy that can be arranged in any way you wish by using drag and drop.
By default, a collection is private, but you can share it on your own subdomain when it's public - more on hosted collections.
You can control the access to public collections with a collection-wide password, guest accounts or by implementing a JWT authentication.
When you add a custom domain, the publish mode is automatically activated. This will allow a staging and a production URL.
Any changes you make to a document are automatically saved, so don't worry about losing your work. The staging environment helps to view the changes before publishing them to the production site.
Archbee generates a static documentation website on the fly. And this is important because most of the documentation websites are not dynamic. Sure, you will have changes, but a static site has benefits when it comes to loading time, SEO advantages compared with, let's say, Single Page Applications.
You can sign up of a free trial and follow the steps below. There is no credit card required or feature limits during the 21 day trial.
How to create a documentation site
Start by getting to know the Archbee interface. In the center, you will find the flexible editor with drag and drop and custom blocks.
On the left, you will find the navigation for Collections and Documents. On the right is the Document outline - a Table of Contents.
To make a documentation site, start by creating a Collection and name it something descriptive like docs.yoursite.com.
When you hover over it, you will see the three dots for the Collection Settings. This is where you will publish the collection.
Click on the Collection Settings, hit the Public toggle, add your custom domain, and just like that, you are set in just a few minutes.
Now your site is ready, and you can view it on the subdomain you added. The best part is that you don't need to think about hosting, CDNs, or SSL certificates because Archbee handles these.
Take care of some essential settings
Before you get started with the content, take a small step that will make the difference later.
The site is visible to search engines.
You can toggle the Indexable by search engines (if public) option from the same Collection Settings. Most of the time, you want this activated so that users find your site on the search engine results page.
Control who access it
You can go to the Public access control option and pick any of the four options for more control.
- None: does exactly what the name says, keeps your settings regarding the public collection.
- Password: Set a collection password. Everyone with the link and password will be able to read the content.
- Guest Accounts: Create guest accounts. Everyone with the link and a guest account will be able to read the content. Guest accounts are not charged as seats in Archbee.
- JWT authentication: Check the doc page for how to set it up. It's a perfect option if you don't want the users to log in each time.
Permalinks and SEO settings
These options are at the document level. So you need to click on the three dots on the top right side and pick SEO Meta Controls.
Add a relevant title, change the URL, write a meta description or upload an image for previews.
Create the structure of the documentation website
Before you write any documentation, think of the main categories that you will cover. This time a pen and paper might help you to draw the structure.
Next, create a document, convert it to a category, and give it a name.
Once you have these, you are ready to add documents under each category.
Start with a document that introduces the main things a user will find on the documentation site. It doesn't have to be complicated; here is how we did it in our User Guide:
- Getting Started
- Hosted Docs
- Import & Export
After you have the structure, you can start creating documents under each category.
When you start to add content, it's essential to have a workflow. Here's a potential one, but you might want to adapt it:
- Start the draft in My Private docs. This will help you write anything that you don't want to share with the team yet.
- When read, move it to the public collection
- Ping a teammate that the doc is ready and needs to review it
- If any, add inline comments where input from other users is required.
- After you are comfortable with the changes, check the staging site.
- If everything looks good, hit publish and announce that everything is live.
Don't forget to add emojis to your categories or categories to make them more visual.
Use templates to produce content faster
Working with templates makes it easy for contributors to start writing content. You can save a set of templates to help you kickstart content production. If you need inspiration, when you create a new document, you will see a button called: Start with a template at the bottom of the page.
To build your own templates, go to the navigation on the left side, Templates, and start creating docs with the structure your documents need.
You might as well introduce the custom blocks that an author will be using or add examples from other sources.
Import content from other sources
Copy-pasting works just fine, but if you have markdown or Word files already formatted, why not import them into a collection.
Before importing any content, make sure you click on the collection where you want to import the files. Click on the type of file you have, and you just saved minutes of copy-pasting from other sources.
Create a navigation menu with multiproduct or product versions
Depending on the type of products or services, you might want to have different collections URL paths.
You can have a collection as the primary docs and create different Collections for other products or even versions of them.
There's a shortcut! You can create a Snapshot of any Collections if the changes are incremental. This will help you keep the structure and make the edits for the new version.
So if versioning and multiproduct is something you need, use a different collection and append it with the relevant path or custom domain.
Go to Collection links and start building your navigation. Add link and dynamically link the collection that you want to show on the live site.
Customize your website
Most of the time, the layout and design are intentionally simple and geared towards readability over style. That’s why in the Public Access tab you will find the banding options like Accent Color, Logo, and Favicon. You can also pick between the Clean or Stripey templates.
The recommendation is to go with Stripey since it will provide more options in terms of navigation and is modeled after the popular Stripe documentation.
Use Custom CSS if you want to add your own flavor to the documentation site. If you are familiar with CSS classes, you will find some starting ab- and you can target them.
Craft a landing page
The main goal of the homepage is to help the visitor go to the next page.
Building a landing page for your documentation website doesn't have to check the same practices for a presentation website.
The first document page is important to introduce your product or service to the users, so keeping it short and setting expectations goes a long way.
You can use the Custom landing page feature and add your HTML for more control over the first page. There are many options to get inspiration from, and if you want to change the look and feel of the first page, this is your option.
Here is how one of our customers built their starting page for their help page.
The features that every documentation website needs
Every docs site is different, kind of. However, most documentation needs the same elements to be considered relevant for the user.
Minimalistic design - The focus is on the content, don't overthink the design.
A stable engine - Pick a documentation site builder that won't crash.
Good and reliable hosting - Avoid downtime; nobody likes a website that cannot be accessed.
Document history - Going back to a previous version of the document should be easy because everybody makes mistakes.
An SEO-friendly structure plays a big role because your users will probably use a search engine to find information about your product.
Good security - what's more to say? Make sure your website won't be hacked.
Reliable backups - in case something goes wrong, you will need them - backup everything.
Search integration - documentation with a lousy search engine won't make your users happy.
Conclusion on how to make a documentation website
That's it; the path to learning how to make a documentation website without a dev team is done!
When using a SaaS to build a documentation website, the cool thing is that you are left with creating the content once you set up the initial settings. And that's where Archbee's block-based editor shines.
That being said, getting your documentation website online is just the start of the journey. Getting people to find valuable information on the website and then keep coming back to it is a whole different challenge.