loading...

Explain like I'm five documentation

mendoza profile image David Mendoza (He/Him) ・1 min read

Hey guys, I hope all of you are trying to be part of #hacktoberfest.
This months my company (web developers for companies) has started to get a lot of projects, and as I was taking a look at the planning I decided to take a break and read some Dev.

well I found this repo

GitHub logo facebook / docusaurus

Easy to maintain open source documentation websites.

Docusaurus

Docusaurus

Twitter Follow npm version CircleCI status PRs Welcome Discord Chat code style: prettier Tested with Jest Gitpod Ready-to-Code Netlify Status

We are working hard on Docusaurus v2. If you are new to Docusaurus, try using the new version instead of v1. See the Docusaurus v2 website for more details.

Introduction

Docusaurus is a project for building, deploying, and maintaining open source project websites easily.

  • Simple to Start

Docusaurus is built in a way so that it can get running in as little time as possible. We've built Docusaurus to handle the website build process so you can focus on your project.

  • Localizable

Docusaurus ships with localization support via CrowdIn. Empower and grow your international community by translating your documentation.

  • Customizable

While Docusaurus ships with the key pages and sections you need to get started, including a home page, a docs section, a blog, and additional support pages, it is also customizable as well to ensure you have a site that is uniquely yours.

Installation

Docusaurus is available…




and I started to think... should this projects have documentations? 🤔
So I think I need to be explained like I'm five documentation...
When should you use it?
Why should you use it?

Discussion

pic
Editor guide
Collapse
nestedsoftware profile image
Nested Software

I think that many open source projects are small/simple enough that the readme file is sufficient to show people how to install and use the project.

For larger libraries and frameworks (think of things like react, webpack, python, etc), more comprehensive documentation becomes necessary. The link you provided is a project that helps to generate and organize the documentation for such larger open source projects. I have not used docusaurus, but the basic idea looks somewhat similar to github.com/readthedocs/readthedocs... (unlike readthedocs, docusaurus does not seem to offer hosting for the documentation; instead it can publish to github pages and other targets).

I am guessing that the documentation for the docusaurus project is generated by docusaurus :)

Collapse
mellen profile image
Matt Ellen

Well, you know how you want to do something and you don't know how, so you go to your parent and you ask:

"I want to change the inner tube on my bike, but I don't know how"

And you parent replies "Ok, hun. I'll come and show you."

And you parent shows you, and now your inner tube has been changed.

But what if your parents weren't around? You still need to change the inner tube on your bike, but you can't ask them.

Luckily you can read, and your parent left instructions for you on how to change the inner tube.

That's documentation. It doesn't cover all types of documentation, but I think it covers the most important part: helping people understand how to use or do something.

The other types of documentation, like risk assessments or specifications, are important, but for people using a project, instructions on how to use it, especially first steps, are very important.