Cách xây dựng tài liệu hệ thống với VuePress

Tạo tài liệu tốt là điều cần thiết cho mọi sản phẩm mà công ty xây dựng, để người dùng giải quyết các vấn đề cụ thể mà họ có thể gặp phải. Tài liệu hệ thống đảm bảo rằng người dùng tiếp tục quay lại để tham khảo tài liệu và không nản lòng khi cố gắng sử dụng trang web tài liệu của bạn.

VuePress là một trình tạo trang web tĩnh phân tích cú pháp các tệp đánh dấu và kết xuất trước chúng dưới dạng tệp HTML cho phía máy khách. Việc tạo ra VuePress là để đơn giản hóa việc phát triển một trang web tài liệu, phục vụ rất nhiều giá trị cho những người đóng góp nguồn mở và cộng đồng nhà phát triển.

Trong bài viết này, bạn sẽ học cách tạo hướng dẫn tài liệu từ một dự án mã nguồn mở hiện có với công nghệ được cung cấp bởi VuePress, đi kèm với Vue, Vue Router và Webpack.

Thử nghiệm

Kiểm tra mã nguồn đã hoàn thành trong repo GitHub này. Fork và chạy mã để bạn tham khảo.

Bản demo trực tiếp cho trang tài liệu hệ thống .

Điều kiện tiên quyết

Nếu bạn muốn hoàn thành hướng dẫn này, bạn sẽ cần:

• Nút> 10+ và sợi được cài đặt trên máy cục bộ của bạn

  
  

Thiết lập dự án

Trong phần này, bạn sẽ tạo một dự án VuePress mới để giúp tạo tài liệu hướng dẫn hệ thống.

Chạy lệnh sau:

 yarn create vuepress-site [optionalDirectoryName]

[optionalDirectoryName] , thay thế nó bằng tên dự án mong muốn của bạn.

Lệnh trên sẽ dàn dựng các tệp và thư mục của dự án và nhắc bạn với các tùy chọn để định cấu hình trang VuePress, trông giống như sau:

Sau khi thiết lập xong, hãy điều hướng đến docs/folder chứa trang tài liệu bằng cách cài đặt các phần phụ thuộc của nó và khởi động máy chủ phát triển bằng các lệnh bên dưới:

 cd docs/ yarn install yarn dev

VuePress đi kèm với tính năng tải lại nóng cập nhật trang web mỗi khi có thay đổi trong quá trình phát triển và có thể truy cập theo mặc định trên http://localhost:8080 .

Tạo tài liệu hệ thống

Trang chủ là trang đầu tiên trên bất kỳ trang web nào. Đây là cơ hội để cho khách truy cập xem một đoạn nội dung của bạn — ấn tượng đầu tiên rất quan trọng.

Trong thư mục docs, trong thư mục src , hãy cập nhật tệp index.md với vấn đề trước YAML sau:

 <!-- 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) :::

Vấn đề phía trên trong tệp Markdown gốc thực hiện như sau:

• home: true : nó xác nhận rằng trang đầu của trang web được hiển thị
• Nó hướng dẫn rằng một image , tagline và văn bản gọi hành động dẫn đến phần bắt đầu /guide/ cho phần còn lại của trang.
• Hiển thị thông tin văn bản footer

Đối với các tài sản phương tiện tĩnh, chẳng hạn như heroImage ở trên, hãy tạo một public mục chung bên trong thư mục .vuepress , với một thư mục khác trong public mục chung có tên img chứa các tệp hình ảnh. Thư mục chung sẽ xử lý và tham chiếu tất cả các nội dung trên trang và sao chép chúng vào thư mục gốc của các tệp tương ứng.

Tiếp theo, hãy cập nhật cấu trúc trong tệp docs/src/.vuepress/config.js .

Sao chép và dán đoạn mã này:

 // 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', ], }, ], }, }, };

Đầu tiên, bạn chỉ định title và description của trang web, tốt cho SEO, được Google lập chỉ mục với các thuộc tính này được đặt. Tương tự như mô tả meta, description được tham chiếu từ tệp package.json trong thư mục docs là những gì hiển thị trên trang kết quả của công cụ tìm kiếm.

Trong đối tượng themeConfig, các tham số được đặt trong tệp config.js như sau:

• Để tạo thanh điều hướng, bạn tạo một mảng nav các đối tượng có chứa văn bản và định tuyến đến từng phần tử nav
• sidebar : Một mảng liên kết hoạt động như điều hướng giữa các trang được đặt trong đối tượng thanh bên

Tạo các trang hướng dẫn

Các trang guide trong phần này sẽ chứa thông tin cụ thể dẫn đến các liên kết hỗ trợ được đặt trong tệp config.js .

Bây giờ, hãy tạo một thư mục trong thư mục docs/src được gọi là guide sẽ chứa các tệp sau:

Trong tệp README.md, hãy sao chép và dán nội dung sau:

 <!-- 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

Lưu ý : Trong VuePress, mọi tệp index.md README.md trong mỗi thư mục con sẽ tự động được chuyển đổi thành index.html với URL tương ứng / .

Đối với phần còn lại của các tệp Markdown riêng lẻ, hãy cập nhật các tệp trong thư mục guide với các thông tin sau:

 <!-- 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 AZ 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)

Trang của bạn sẽ trông như thế này:

Bớt tư tưởng

Trong hướng dẫn này, bạn đã phát triển một hướng dẫn tài liệu hệ thống bằng VuePress cung cấp một ứng dụng một trang cho các dự án nguồn mở yêu thích của bạn. Sử dụng VuePress, bạn có thể tạo các ứng dụng nhanh chóng và có thể mở rộng trong thời gian ngắn hơn.

Tìm hiểu thêm

• Tài liệu VuePress
• Sử dụng Navbar trong VuePress