A better documentation website?

[danawoodman]

Mongoose is great but, in this mans opinion, the documentation website (mongoosejs.com) is sorely lacking. Are there currently plans to improve the structure and functionality of the documentation site?

Here are some notes on issues as I see it and potential solutions:

Single-page Docs

Having everything on one page makes finding and linking to content a huge pain. Google often just brings you to the top of the huge API doc page. This causes a few issues including poor searching experience via search engines, lots of scrolling, etc

I would propose having an individual page for each main section (Schema, Document, Query, etc) where one can drill down into classes/methods, something like MDN's docs:

Content

A lot of the documentation is slightly useless and seems to be a product of auto-generated docs. For example, in this screenshot all you see is a self-referential link with a useless descriptor. This is even the case on the very first link on the API docs site (eg index.js)

I would suggest that these types of documentation are either updated to link to actual documentation or removed in the build process.

Sidebar

The sidebar is less than helpful for actual navigation as it has no apparent logical structure besides grouping by folder. The arrows dont work reliably and often requires clicking twice to open. Grouping things by file name/folder is doesn't add anything from the end users perspective:

Having a sidebar broken down by section or sorted in some meaningful way would be very nice.

Search

The lack of a search feature makes navigating the large amount of documentation difficult, time consuming and frustrating.

An auto-complete search box placed in a prominent location would be great, something akin to Bootstrap v4 docs:

Examples

There is also a general lack of examples on the site making it difficult to learn how to use various features. Often StackOverflow is a more reliable place to go to learn more.

Design

On a more nitpicking note, the left-aligned content and the slightly undersized fonts make legibility a bit degraded. Even more of an opinion, I find the typography a bit outdated and the color scheme feels "tired".

In Summary...

I offer these notes not to criticize but to start a conversation about improving the end user experience of Mongoose users. Thanks for all your hard work building Mongoose!

PS I'd be happy to throw together some wireframes/mockups if there is interest in such things.

[sibelius]

👍

We should use a structure like Redux docs (https://github.com/reactjs/react-redux)

They use .md instead of html or jade, that is easy to modify
They use gitbook for this

[Jeff-Lewis]

http://devdocs.io/mongoose/

[Lxrd-AJ]

+1

[danawoodman]

@Jeff-Lewis yeah, that is my fallback but IMO the default docs should serve that job just as well. Besides, many developers aren't aware of the (awesome) devdocs.io site.

@sibeliusseraphini the Redux docks are nice (gitbooks). I have a few nitpicks about it but it would be a major improvement over the current state.

Anyone with the Mongoose team think this is worth pursuing?

[vkarpov15]

Thanks for the detailed suggestions. I'm definitely looking to rework the docs in the near future, but any help is appreciated :)

[danawoodman]

@vkarpov15 let me know how I could be of help or what specifically you think is doable, at least in the short term

[vkarpov15]

Short term plan is to convert all the guides to use acquit, so our guides and API docs are all in a nice structured format that's easy to refactor (#3392). After that, restructuring the API docs, because right now they're not terribly useful, and improving the layout.

[Fonger]

Is mongoose's doc generated by jsdoc ?

[vkarpov15]

dox and acquit

[danawoodman]

So does that mean docs are generated from tests as well as docstrings?

[vkarpov15]

Right now there's 3 ways:

• The .jade files in docs/. That's on its way out.
• The tests in test/docs are replacing the above slowly (acquit)
• The comments in the code itself (dox)