Mongoose: 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]

:+1:

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)

[checkmatez]

Any update on this? Docs are really not very nice to use at the moment...

[osenvosem]

Better documentation would be nice to have. People really experience difficulties with the current.

[nharrisanalyst]

has there been any progress on this I am a seasoned front end dev learning back end and it seems anything in the docs that doesn't have an example is very hard to intuitively discern how to use.

I would be willing to help if someone could point me in the direction on how to help.

[vkarpov15]

@nharrisanalyst are you good with design? Could definitely use someone with some CSS chops to help out

[sibelius]

what about this one https://github.com/facebook/Docusaurus

[nharrisanalyst]

Im not the best at CSS but Im also not bad what design work needs to be done?

[vkarpov15]

I have some rough mockups but looking for someone with experience with responsive design to help me make sure they work right on different resolutions. If you're interested, let's discuss over email (val at karpov dot io), so we don't spam people's inboxes with github notifications.

[benedictchen]

It would be really nice to have mongoose JSDocs. I can't really understand what is expected in the params and it takes me forever to figure it out.

[vkarpov15]

@benedictchen can you clarify what you mean by "mongoose JSDocs" and where you're getting info on what is expected in params?

[benedictchen]

Putting the params and return expectations in each JSDoc, then generating a
website with it so developers know clearly what comes out of a query.
http://usejsdoc.org/about-getting-started.html#generating-a-website

On Tue, Mar 13, 2018 at 2:49 PM, Valeri Karpov [e-mail]
wrote:

@benedictchen https://github.com/benedictchen can you clarify what you
mean by "mongoose JSDocs" and where you're getting info on what is expected
in params?

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/Automattic/mongoose/issues/3921#issuecomment-372830398,
or mute the thread
https://github.com/notifications/unsubscribe-auth/ABL5Z_f6vExhc9FE1RUi7M6e6fuojg1oks5teD7rgaJpZM4Hkjji
.

[bidiu]

The doc is so bad... It's funny that I can't even know what a function will return....

[vkarpov15]

@bidiu which function in particular are you talking about?

[horoscop]

@vkarpov15 Hi! Could you please collaborate with some other mongoose tech leads to provide better documentation? VueJS docs are a model, in my opinion.
First thing, please change the design of the site, it's counter productive. You need to guide people to the most important chunk of info. Don't get me wrong, but it needs to e changed.

[vkarpov15]

@horoscop do you have any concrete suggestions? What exactly are the most important chunks of info in your opinion?

[hakrac]

@vkarpov15: What this doc is missing is consistency and clarity.
As an example look at the note for Model.updateOne:

MongoDB will update only the first document that matches criteria regardless of the value of the multi option.

The point is in the parameter list the criteria parameter is called condition which leads to confusion.

[deepakk1234kd]

Hi,
I am new to mongoosejs, so please correct me if I am wrong.

I feel that some documentation might be missing. Recently, I had to google how to get all the paths/attributes for a mongoose model, I saw in Stack Overflow that you can get them via 'Object.keys(.schema.paths)'. But as per this page 'https://mongoosejs.com/docs/api/schema.html', I did not find any 'paths' property.

So am I looking in the wrong place or is it missing in the documentation?