Repository navigation
Clean up docs #211
Description
Activity
I would add that it could really use a guide as well.
The Vue.js website has been lauded as the gold standard for documentation. It splits the site into 2 parts
- Guide:
- Aimed at first-time visitors, likely unfamiliar with the technology
- Walks you through the absolute basics, step-by-step.
- Gets to "the point" very quickly, showing you the value proposition of why you should use it almost immediately.
- Slowly increases complexity as it adds more examples.
- Fully interactive, so you can learn by playing around (interactive Scrimba videos and JSFiddle links)
- Sidebar documents the different sections of the guide and what they focus on (outcomes, not API)
- Expectation is that the user knows absolutely nothing.
- For example, I still don't really understand
Array[string],string[],[key: string]: any, or{ [key: string]: Function }. There NEEDS to be a page that just explains all of these cryptic variations on type descriptors, and it would fit perfectly in the guide.
- For example, I still don't really understand
- API:
- Sidebar organized by API.
- Aimed at those already familiar with the technology that just need to look something up quickly.
- Easily searchable.
- Lots of examples.
- This is mostly done on the current JSDocs site, could just use some fresh CSS and a once-over to make the text a little simpler to understand.
- Guide:
try this https://github.com/kejunmao/jsdoc
preview: https://vjsdoc.netlify.app/
Reacted by Graham
JSDoc is amazing, but it's docs are hard to use and somewhat ugly. I've outlined some issues below.
No sidebar
When you go to a page, you have to go back to the home page to find other pages. This makes it harder to find interesting pages.
2010 styling
The website looks like it's from 2010. It's pretty bad.
No search
If you can't search, you have to find pages yourself. Something like Algolia Docsearch is free and easy to implement.