How to Build System Documentation with VuePress

Written by terieyenike | Published 2022/07/22
Tech Story Tags: javascript | programming | vue | vuepress | open-source | blogging-fellowship | front-end-development | hackernoon-top-story

TLDRVuePress is a static site generator that parses markdown files and prerenders them as HTML files for the client-side. It ships with Vue, Vue Router, and Webpack. The guide is written by Teri Eyenike, an open-source project with a technology powered by VuePress. It's an opportunity to show visitors a snippet of what you’re about with the front page. The homepage is the first page on any website, and it’s an opportunity for visitors to see snippets of information.via the TL;DR App

Creating good documentation is essential for every product a company builds, for its users to solve specific problems they might encounter. System documentation ensures that users keep returning to reference the documents and are not frustrated trying to use your documentation site.

VuePress is a static site generator that parses markdown files and prerenders them as HTML files for the client-side. VuePress creation is to simplify the development of a documentation site, serving a great deal of value to open-source contributors and the developer community.

In this article, you will learn how to create a documentation guide from an existing open-source project with a technology powered by VuePress, which ships with Vue, Vue Router, and Webpack.

Demo

Check the completed source code in this GitHub repo. Fork it and run the code for your reference.

Live demo for the system documentation site.

Prerequisites

If you would like to complete this guide, you will need:

Setting Up the Project

In this section, you will create a new VuePress project to help make the system documentation guide.

Run the following command:

yarn create vuepress-site [optionalDirectoryName]

The [optionalDirectoryName], replace it with your desired project name.

The above command scaffolds the project files and folders and prompts you with options to configure the VuePress site, which should look something like this:

With the setup done, navigate to the docs/folder that contains the documentation site by installing its dependencies and start the development server with the commands below:

cd docs/

yarn install

yarn dev

VuePress comes packed with the hot reload feature that updates the site each time a change occurs during development, and it is accessible by default on http://localhost:8080.

Creating the System Documentation

The homepage is the first page on any website. It’s an opportunity to show visitors a snippet of what you’re about—first impressions matter.

Under the docs directory, in the src folder, update the index.md file with the following YAML front matter:

<!-- docs/src/index.md -->

---
home: true
heroImage: img/technical_writing_logo.png
tagline: Technical writing is a form of communication that helps users solve problems with technology. As a technical writer, sharing your knowledge and experience with people helps you affirm that you have a solid understanding of the technology you're writing about.
actionText: Get Started →
actionLink: /guide/
---


::: slot footer
MIT Licensed | Copyright © 2022 [Teri Eyenike](https://twitter.com/terieyenike)
:::

The above front matter in the root Markdown file does the following:

  • home: true: it validates that the front page of the website is displayed
  • It instructs that an image, tagline, and call-to-action text lead to the get started /guide/ for the rest of the page.
  • Display the footer text information

For the static media assets, such as the heroImage above, create a public folder inside the .vuepress directory, with another folder within the public folder called img that holds the image files. The public folder will handle and reference all assets on the page and copy them to the root of their respective files.

Next, let’s update the structure in the docs/src/.vuepress/config.js file.

Copy and paste this snippet of code:

// docs/src/.vuepress/config.js

const { description } = require('../../package');

module.exports = {
  title: 'Technical writing resources',
  description: description,
  themeConfig: {
    searchPlaceholder: 'Search...',
    nav: [
      {
        text: 'Guide',
        link: '/guide/',
      },
      {
        text: 'GitHub',
        link: 'https://github.com/dharmelolar/technical-writing-resources/',
      },
    ],
    sidebar: {
      '/guide/': [
        {
          title: 'Guide',
          collapsable: false,
          children: [
            '',
            'articles',
            'books',
            'courses',
            'youtube',
            'communities',
            'tools',
            'who-pay',
            'open-source',
            'open-projects.md',
            'blogs',
            'interviews',
            'publication',
            'job-boards',
          ],
        },
      ],
    },
  },
};

First, you specify the website's title and description, which is good for SEO, indexed by Google with these attributes set. Similar to the meta description, the description referenced from the package.json file in the docsfolder is what displays on the search engine result page.

In the themeConfig object, the parameters set in the config.js file are as follows:

  • To create a navbar, you generate a nav array of objects that contains the text and route to each nav element
  • sidebar: An array of links that act as navigation between pages set in the sidebar object

Creating the Guide Pages

The guide pages in this section will contain specific information that leads to the supporting links set in the config.jsfile.

Now, let’s create a folder in the docs/src folder called a guide that will contain the following files:

In the README.md file, copy and paste the following:

<!-- docs/src/guide/README.md -->

# What is Technical Writing?
Technical writing is a type of writing where the author is writing about a particularsubject that requires direction, instruction, or explanation. This style of writing has a very different purpose and different characteristics than other writing styles. ~ [YourDictionary](https://grammar.yourdictionary.com/word-definitions/definition-of-technical-writing.html)

## Resources
This repository contains different technical writing resources that has been gatheredfrom all around the internet


Note: In VuePress, every README.md or index.md file contained in each sub-directory will automatically be converted to index.html with its corresponding URL /.

For the rest of the individual Markdown files, update the files in the guide folder with the following:

<!-- docs/src/guide/articles.md -->

# Articles

- [How to Get Started with Technical Writing](https://www.samjulien.com/how-to-get-started-with-technical-writing)

- [How to become a technical writer](https://www.freecodecamp.org/news/how-to-become-a-technical-writer/)

- [Technical Writing for Beginners – An A-Z Guide to Tech Blogging Basics](https://www.freecodecamp.org/news/technical-writing-for-beginners/)

- [Technical Writing: What and How?](https://edidiongasikpo.com/technical-writing-what-and-how)

- [How to Learn Technical Writing for Free](https://medium.com/technical-writing-is-easy/how-to-learn-technical-writing-for-free-c16d191b3cee)

- [Getting Started with Technical Writing](https://dillionmegida.com/p/getting-started-with-technical-writing/)

- [Advice for Technical Writing](https://css-tricks.com/advice-for-technical-writing/)

- [How To Write Content That Readers Will Read Based On Learnings From User Psychology](https://www.everythingtechnicalwriting.com/how-to-write-content-that-readers-will-read/)

- [How To Create A Technical Writing Portfolio](https://www.everythingtechnicalwriting.com/technical-writing-portfolio/)

- [Writing Tips for Software Developers – How to Become a Better Tech Writer](https://www.freecodecamp.org/news/writing-tips-software-developers/)

- [11 Best Practices for Writing API Documentation](https://treblle.com/blog/11-best-practices-for-writing-api-documentation)

- [Technical Writing vs Technical Blogging](https://lo-victoria.com/what-you-need-to-know-about-technical-writing-vs-technical-blogging#cknj3ppa30d7m2ks14c8o0vnf)


<!-- docs/src/guide/blogs.md -->

# Blogs to follow for awesome writing contents

| Technical Writers | Blogs                                      | Twitter Handle                                          |
| :---------------- | ------------------------------------------ | ------------------------------------------------------- |
| Damilola Ezekiel  | https://dharmelolar.hashnode.dev           | [@that_yhemmygirl](https://twitter.com/that_yhemmygirl) |
| Tom Johnson       | https://idratherbewriting.com/             | [@tomjohnson](https://twitter.com/tomjohnson)           |
| Kesi Parker       | https://medium.com/@kesiparker             | [@ParkerKesi](https://twitter.com/ParkerKesi)           |
| Tania Rascia      | https://tania.dev/                         | [@taniarascia](https://twitter.com/taniarascia)         |
| Dillion Megida    | https://writing.dillionmegida.com/         | [@iamdillion](https://twitter.com/iamdillion)           |
| Linda Ikechukwu   | https://www.everythingtechnicalwriting.com | [\_MsLinda](https://twitter.com/_MsLinda)               |
| Amruta Ranade     | https://dev.to/amrutaranade                | [@AmrutaRanade](https://twitter.com/AmrutaRanade)       |


<!-- docs/src/guide/books.md -->

# Books

- [Writing Well](https://www.julian.com/guide/write/intro) ~ Julian Shapiro
- [Technical Writing, Simplified](https://www.amazon.com/Technical-Writing-Simplified-Nell-Johnson/dp/154326848X/ref=sr_1_1?crid=NUEHTLJWKLMN&keywords=Technical+Writing%2C+Simplified&qid=1651614066&s=books&sprefix=technical+writing%2C+simplified%2Cstripbooks-intl-ship%2C416&sr=1-1) ~ Nell Johnson
- [Writing for Sotware Developers](https://philipkiely.gumroad.com/l/uZPZU) ~ Philip Kiely
- [Technical Writing For Dummies](https://www.amazon.com/Technical-Writing-Dummies-Sheryl-Lindsell-Roberts/dp/0764553089) ~ Sheryl Lindsell-Roberts

- [Docs for Developers: An Engineer’s Field Guide to Technical Writing](https://www.amazon.com/Docs-Developers-Engineers-Technical-Writing/dp/1484272161/) ~ Jared Bhatti
- [Modern Technical Writing: An Introduction to Software Documentation ](https://www.amazon.com/Modern-Technical-Writing-Introduction-Documentation-ebook/dp/B01A2QL9SS/ref=sr_1_1?crid=Y7S35M7LVXWE&dchild=1&keywords=modern+technical+writing&qid=1595414707&sprefix=modern+technical+%2Caps%2C346&sr=8-1) ~ Andrew Etter
- [Everybody Writes: Your Go-To Guide to Creating Ridiculously Good Content](https://www.amazon.com/gp/product/1118905555/ref=as_li_tl?ie=UTF8&tag=techlife09-20&camp=1789&creative=9325&linkCode=as2&creativeASIN=1118905555&linkId=5a9769d7dc1a62419abb83e6b451ac96) ~ Ann Handley
- [On Writing Well](https://www.amazon.com/gp/product/0060891548/ref=as_li_tl?ie=UTF8&tag=techlife09-20&camp=1789&creative=9325&linkCode=as2&creativeASIN=0060891548&linkId=27bd72a8da3fb242b39dbe4edb470daf) ~ William Zinsser
- [Technical Communication](https://www.amazon.com/Technical-Communication-Mike-Markel-dp-1319245005/dp/1319245005/ref=dp_ob_image_bk) ~ Mike Markel


<!-- docs/src/guide/communities.md -->

# Communities

Communities can provide valuable learning opportunities, growth, mentorship and career advancement. Connecting with people of similar interest is one of the reasons why people join communities. Here are some of the communities that technical writers can join:

- [Write the Docs](https://www.writethedocs.org/)

- [Linkedin Technical Writing Community](https://www.linkedin.com/groups/13705342/)

- [Global Writers Community](https://web.facebook.com/groups/technicalwriterjobs/?_rdc=1&_rdr)

- [API Documentation Group](https://www.linkedin.com/groups/3709151/)

- [Technical Writer Forum](https://www.linkedin.com/groups/112571/)

- [Hashnode](https://discord.com/invite/hashnode)

- [The Good Docs Project Community](https://thegooddocsproject.dev/community/)

- [Techwriters.dev](https://techwriters.dev/)

- [r/technicalwriting](https://www.reddit.com/r/technicalwriting/)


<!-- docs/src/guide/courses.md -->

# Courses

- [Technical Writing Courses for Engineers](https://developers.google.com/tech-writing)

- [Technical Writing: How to Write Software Documentation](https://www.udemy.com/course/start-your-career-as-user-assistance-developer/)

- [Learn API Technical Writing: JSON and XML for Writers](https://www.udemy.com/course/api-documentation-1-json-and-xml/)

- [The Art of API Documentation](https://www.udemy.com/course/the-art-of-api-documentation/)

- [Documenting APIs: A guide for technical writers and engineers](https://idratherbewriting.com/learnapidoc/)

- [Technical Writer Certification Course](https://technicalwriter.teachable.com/p/technical-writing-certification) ~ Technical Writer Certification Course was created for aspiring technical writers or people who want to brush up on their technical writing skills.

- [SEO FOR DEVS](https://seofordevs.com/) ~ SEO FOR DEVS is a free 2 weeks course that helps people discover your tech blog or side project in a systematic way

- [API Documentation for Developers](https://apidocsfordevs.com/) ~ A hands-on guide to creating and maintaining API documentation.


<!-- docs/src/guide/interviews.md -->

# Preparing for technical writing interviews

There are several tips that can help you land an interview but some of the important ones are having a well tailored resume and cover letters. Check out these cover letter templates and tips to help you land your next interview:

- [Cover Letter Template for your next job ](https://dillionmegida.com/p/cover-letter-template/)

- [How to Write an Enticing Cover Letter](https://ruthikegah.xyz/how-to-write-an-enticing-cover-letter)

- [How to Write a Technical Writer Resume [+Examples]](https://technicalwriterhq.com/technical-writer-resume/)

- [Best Technical Writer Cover Letter Example and Format ](https://technicalwriterhq.com/technical-writer-cover-letter/)

Here are some resources to technical writing interview questions to help you prepare for your next interview.

- [12 Technical Writer Interview Questions and Answers](https://technicalwriterhq.com/technical-writer-interview-questions/)

- [Google Technical Writer Interview Questions](https://technicalwriterhq.com/google-technical-writer-interview-questions/)

- [Technical Writing Job Interview](https://www.youtube.com/watch?v=cqaEgMv2JAg)


<!-- docs/src/guide/job-boards.md -->

# Job Boards For Technical Writing roles

- [Startup.jobs](https://startup.jobs/?q=Technical+writer&remote=true&utm_campaign=Everything+Technical+Writing+Newsletter&utm_medium=email&utm_source=Revue+newsletter)

- [Angel.co](https://angel.co/jobs)

- [Content Writing Jobs](https://contentwritingjobs.com/)


<!-- docs/src/guide/open-projects.md -->

# Open Source Projects/Programs Technical Writers Can Contribute To

- [Codecademy Docs](https://www.codecademy.com/resources/docs) ~ Docs is a community-driven collection of code documentation for popular programming languages and frameworks.

- [The Good Docs Project](https://thegooddocsproject.dev/) ~ The Good Docs Project is a community working together to create the templates, tools, and resources to improve the overall quality of documentation in OSS and beyond.

- [Google Season of Docs](https://developers.google.com/season-of-docs) ~ Season of Docs provides support for open source projects to improve their documentation and gives professional technical writers an opportunity to gain experience in open source.

- [Hacktoberfest](https://hacktoberfest.digitalocean.com/) ~ Hacktoberfest is a yearly event to encourage people to contribute to open source in October.

- [The GNOME Documentation Project](https://wiki.gnome.org/DocumentationProject)


<!-- docs/src/guide/open-source.md -->

# Open Source Projects

Contributing to open source can be a rewarding way to learn, teach, and build experience in just about any skill you can imagine. A lot of peole contribute to open source for different reasons and the vital one which is improving one's skillset.

Here are some articles to help you understand how to contribute to open source projects.

- [The Technical Writers Guide to Contributing to Open Source Projects](https://edidiongasikpo.com/the-technical-writers-guide-to-contributing-to-open-source-projects)

- [How to Contribute to Open-Source as a Technical Writer](https://javascript.plainenglish.io/how-to-contribute-to-open-source-as-a-technical-writer-bb708245480c)

- [4 tips to becoming a technical writer with open source contributions](https://opensource.com/article/21/11/technical-writing-open-source)

- [Getting started with Open Source as a Technical Writer](https://amara.hashnode.dev/getting-started-with-open-source-as-a-technical-writer)


<!-- docs/src/guide/publication.md -->

# Sites to publish articles

- [Hashnode](https://hashnode.com/) ~ Hashnode is a free developer blogging platform to help you share your ideas with people in tech, developers, and engineers.

- [Medium](https://medium.com/) ~ Medium is a social publishing platform with lots of users and you can publish diverse contents and ideas.

- [Dev.to](https://dev.to/) ~ Dev.to is where programmers share ideas and help each other grow. It is an online community for sharing and discovering great ideas.

- [Mirror.xyz](https://mirror.xyz/) ~ Mirror.xyz is a publishing platform for writers that leverages cryptocurrency and blockchain technology.

- [Freecodecamp](https://www.freecodecamp.org/news/how-to-write-for-freecodecamp/) ~ FreeCodeCamp is a non-profit organization that consists of an interactive learning web platform, an online community forum, chat rooms, online publications and local organizations that intend to make learning web development accessible to anyone.


<!-- docs/src/guide/tools.md -->

# Tools

- [Canva](https://www.canva.com/) ~ Canva is a graphic design platform, used to create social media graphics, presentations, posters, documents and other visual content.

- [Removebg](https://www.remove.bg/) ~ A tools that is used to remove image backgrounds.

- [Markdown](https://daringfireball.net/projects/markdown/) ~ Markdown is a text-to-HTML conversion tool for web writers.

- [AsciiDoc](https://asciidoc.org/) ~ AsciiDoc is a lightweight and semantic markup language primarily designed for writing technical documentation.

- [Denigma](https://denigma.app/) ~ Denigma is a tool that explains code in understandable english.

- [Grammarly](https://app.grammarly.com/) ~ Grammarly is a typing assistant that reviews spelling, grammar, punctuation, clarity, engagement, and delivery mistakes.

- [Hemingway App ](https://hemingwayapp.com/) ~ The Hemingway App is a web and desktop app that can improve your writing style and touch up your content.

- [Quillbot AI](https://quillbot.com/) ~ Quillbot AI is a multi-purpose writing tool that can assist in improving your writing style. Some of its products are Paraphraser, Grammar Checker, Plagiarism Checker, Co-Writer, Summarizer, Citation Generator, and Word Counter.

- [Notion](https://www.notion.so/) ~ Notion is an all-in-one workspace for your notes, tasks, wikis, and databases. It is a tool you can use to organize your thoughts, projects, and information.

- [Dropbox Paper](https://www.dropbox.com/paper) ~ Dropbox Paper is an online document workspace, where you can organize and display text, media, and files all in one place.

- [GoFullPage - Full Page Screen Capture](https://chrome.google.com/webstore/detail/gofullpage-full-page-scre/fdpohaocaechififmbbbbbknoalclacl?hl=en) ~ A chrome extension taht allows you take full page screenshot of your current browser window.

- [Carbon](https://carbon.now.sh/) ~ Carbon is the easiest way to create and share beautiful images of your source code.

- [Isitwp](https://www.isitwp.com/headline-analyzer) ~ IsItWP Headline Analyzer tool helps you write headlines that drive traffic, shares and rank better in search results.

- [Capitalize my title](https://capitalizemytitle.com/) ~ Making title capitalization easy for your writing

- [Wordtune](https://www.wordtune.com/) ~ Wordtune turns text into concise, engaging, well-written messages.

- [Headline Analyzer](https://coschedule.com/headline-analyzer) ~ Write Headlines That Drive Traffic, Shares, And Search Results.

- [Title Generator](https://tweakyourbiz.com/title-generator) ~ Generate great titles for articles and blog posts.

- [SEO writing assistant](https://www.semrush.com/swa/) ~ A smart writing editor that helps you optimize your copy for engagement and SEO.

- [HackMD](https://hackmd.io/) ~ A collaborative markdown editor for sharing your articles and getting feedback from others.

- [Copyscape](https://www.copyscape.com/) ~ Plagiarism checker

- [MarkDoc](https://markdoc.io/) ~ A superset of Markdown for creating custom documentation websites. It was created by Stripe and made open source in May 2022.

- [Wordtune](https://www.wordtune.com/) ~ Wordtune is an AI- powered writing companion that rephrases your sentences to say exactly what you mean through clear, compelling, and authentic writing.


<!-- docs/src/guide/who-pay.md -->

# Who pays technical writers

Writing technical contents for organizations and publications is an excellent way to earn extra income. This way, you learn a lot, then share your knowledge and get paid. Check out these compiled list for organizations that pays technical writers.

- [Community writer program](https://github.com/malgamves/CommunityWriterPrograms)

- [Get Paid to Write for These 45+ Websites](https://blog.idrisolubisi.com/get-paid-to-write-for-these-45-websites)

- [Publications That Pay You To Write Technical Articles](https://catalins.tech/websites-that-pay-you-to-write-technical-articles)


<!-- docs/src/guide/youtube.md -->

# Youtube

- [DocToHelpTV](https://www.youtube.com/user/DocToHelpTV/videos)

- [Technical Writer HQ](youtube.com/channel/UCjMnGjosWhBxYtumwhQLZmA/videos)

- [Amruta Ranade](https://www.youtube.com/channel/UCKsaZMjb3lsLe5YtasDifuA)

- [William Smith](https://www.youtube.com/watch?v=amKDhaIlyOc)

- [How to become a Technical Writer | Skills & Career Growth](youtube.com/watch?v=8l2KJXIBpB0)

Your page should look like this:


Closing Thoughts

In this tutorial, you developed a system documentation guide using VuePress that offers a single-page application for your favorite open-source projects. Using VuePress, you can build fast and scalable apps in less time.

Learn More

Written by terieyenike | I am a frontend developer with a particular interest in making things simple and usable.
Published by HackerNoon on 2022/07/22
ABOUTHow hackers start their afternoons. We publish tech stories and build publishing software.

READEntirely free library read by hundreds of millions to learn anything about any technology.

WRITEHackerNoon elevates quality technology writing far and wide across the interwebs.

PARTNERHackerNoon works directly with tech companies to place ads by content relevancy