adminjs

adminjs copied to clipboard

Describe the problem feature solves The documentation for the project leaves a great deal to be desired. It is trial and error trying to figure out what is even possible and what isn't, and the format of how to implement it. To be honest, this is some of the least useful documentation I've seen and makes working with the project a painful experience. Many of the issues filed here on github seem to be due to the fact that the documentation leaves people feeling in the dark.

(Adding to this, and a separate issue, is the fact that errors seem hidden from the user. At least with poor documentation, you can look to those but when there are query, misconfiguration or validation errors, there is no useful logging to enable you to debug these issues.)

Describe the solution you'd like I think the documentation needs to be completely rewritten with:

• Clear, complete functional examples of what the software can do and how to configure it. Not fragments of objects, or descriptions without actual code.
• Examples of advanced usage with complex setups, not just the most basic setup.
• List of features that are supported or not supported (eg. many to many relationships), and whether they will be in the future.

I think the software is good, and useful, and would like to use it, but it's really being let down by this side.

Great feedback, and Im sure this is what everyone is hoping for in the community. But this seems like a huge undertaking and perhaps you can suggest a solid first step to this problem (e.g. providing a list of other well-written documentation?). I would love to help.

This is definitely no small amount of work, and would probably require a slow down on new development to ensure the existing set of features is properly documented.

Some good documentation to take a look at: https://guides.emberjs.com/release/ - very clear, detailed, and fleshed out https://www.typescriptlang.org/docs/handbook/intro.html - a much bigger project that has very comprehensive guides, examples, and API reference

I also found this article that has some pretty good points to consider when writing: https://dzone.com/articles/the-anatomy-of-a-great-open-source-documentation-h

In case the organisation is interested in this, applications specifically for funding documentation for open source are being taken now as part of Google's Season of Docs: https://developers.google.com/season-of-docs

I can't give an ETA right now but we do plan to extend the documentation, especially by adding and improving current tutorials section. Ideally, it would be something similar to NestJS Recipes: https://docs.nestjs.com/recipes/crud-generator

We've recently updated our dev/documentation repository: https://github.com/SoftwareBrothers/adminjs-dev which should speed up our efficiency plus we now have an easier way of maintaining the documentation (in it's current format) which should currently be 99% up to date.

Hey, the docs is currently rewritten to new format, we'll work on improving it further.