# Why use this 🎉 ...?

# Documentation is often out of date

While no documentation for a project can be a frustrating experience, it is arguably worse to have outdated documentation. After all, the purpose of having documentation is to provide users with an official body of knowledge that they can rely on. When it is out of date, users are wasting their time and ultimately losing trust in your product.

# VuePress Can Co-Exist With Your Existing Codebase

When it comes to maintaining documentation, one way to guarantee it will go out of date is to make it difficult for developers to update docs when writing code. If you make the authoring experience difficult by forcing developers to update things in two different places, this will cause a lot of friction and often results in documentation getting left to the wayside. This is commonly seen when developers have to maintain a third party tool like a wiki, in addition to the codebase itself.

Because it is a static site generator, this means that it can live in the same exact repo as your code.

As you can see in this sample web app structure, your code would live in the src directory as normal, but you would simply have a docs directory to contain all of your documentation. This means you get the benefits of

• All documentation is now version controlled;
• Pull requests can now contain both documentation and code changes;
• Creating separate scripts for running local instances of your code and docs at the same time;
• Utilize build pipelines to determine whether new documentation site deployments go in sync with code deployments or not.

# The Default Theme Comes With Standard Configuration

Writing documentation is hard enough as it is, so VuePress offloads a lot of the decisions that one normally has to make and has a bunch of built-in defaults to make your authoring experience easy:

• Writing content is done primarily with Markdown.

  This means that you can leverage your existing knowledge of Markdown syntax to style and format your text.

  

# Reliable Search Functionality

No matter how much time we spend writing great documentation, it will ultimately amount to being useless if the users can’t find it. There are generally two approaches to this:

1. Wait for search engine robots to slowly crawl your site in hopes that one day your users will be able to find the right page on your site. Not a great solution.

2. Build your own search functionality, but this can be difficult to implement for static sites as there’s no server-side code running to create search indexes and perform the lookups. Not to mention this is taking development time away from the product itself. So this isn’t great either.

---

# Automatic Generation Of Important Meta-Data That’s Commonly Overlooked

One of the most frustrating things that a user can encounter is out-of-date documentation. When a user follows the steps and has trouble understanding why something doesn’t work, being able to easily find out the last updated date can be incredibly useful to both the user and maintainers of the project.

With a simple configuration, VuePress can ensure automatically output the last updated date on the page so your users always know the last time it was updated. A screenshot to show the ‘Last Updated’ metadata field

# Service workers

VuePress has an option in the config that allows it to automatically generate and register a service worker that would cache the content for offline use.

# Performance & SEO

Each page generated by VuePress has its own pre-rendered static HTML, providing great loading performance and is SEO-friendly. Yet, once the page is loaded, Vue takes over the static content and turns it into a full Single-Page Application (SPA). Extra pages are fetched on demand as the user navigates around the site.