Next iteration of the docs

[adrianthedev]

The docs have evolved quite a bit, and we need to think of a way to refactor/reorganize them.

Let's use this issue to collect all the feedback we received.

• https://github.com/avo-hq/avo/discussions/1144#discussioncomment-8645974
• add an avo.rb page where we talk about each feature from the initializer.
• https://github.com/avo-hq/avodocs/issues/195

[Paul-Bob]

Sometimes syntax change several times, on the docs it's hard to follow all the warnings: use this on version x and that on y or use this on last version. We should somehow manage the docs according to the selected version. Let's find a way to do that without duplicate all docs pages for each version.

[sedubois]

• [ ] The use_resource section of https://docs.avohq.io/3.0/field-options.html is empty
• [x] The avohq.io landing page is still linking to Avo 2 docs. In the section "All the tools you need to build your new app fast", e.g. click "Fantastic CRUD UI", it goes to https://docs.avohq.io/2.0/resources.html.
• [ ] The avohq.io "Full mobile interface" and "Multi-tenancy" links under "All the tools you need to build your new app fast" just link to the current page, avohq.io.
• [ ] the filters page doesn't indicate in which plan it's available unlike with other pages (this is an example; other doc pages could be reviewed too)
• [ ] the filters page doesn't show a screenshot/animation of what it's about (first image is only found when navigating to "basic filters" then scrolling a few screens down the page) (this is an example; other doc pages could be reviewed too)

[sedubois]

• Broken video play button placement on mobile
• consider using center alignment for "Read what our customers ... " CTA

[Paul-Bob]

The avohq.io landing page is still linking to Avo 2 docs. In the section "All the tools you need to build your new app fast", e.g. click "Fantastic CRUD UI", it goes to https://docs.avohq.io/2.0/resources.html.

Thank you, fixed

[sedubois]

I would find it helpful to have visual highlights of Avo's main features somewhere prominent, such as on avohq.io in the features section ("All the tools you need to build your new app fast") and at the beginning of the documentation.

For instance, it is only after a long time that I discovered "Actions" and understood what they looked like, because it's a feature "hidden" at the end of the demo video on avohq.io.

The avohq.io landing page has a grid with feature names such as "Actions", "Filters", etc but it would be more visually compelling and clearer if this showed images/GIFs too. Such GIFs are already available for some features within their doc pages (e.g. for actions), so perhaps those ones could just be reused.

Alongside (or alternately to) the visuals, there could also be code snippets.

It would be even better if there was a widget showing the actual feature. For instance for the Actions feature, display an index view with the "Actions" button (already opened) and let the user click one of its entries to run a dummy action).

So each feature card could be progressively enhanced with:

• title, description and anything else marketing-friendly
• visual (still image or animation)
• code snippet
• demo widget
• link to learn more
• an indication of which plan this is available in

[sedubois]

Landing page issues:

• Typo: "trully" seamless updates

• Listing "actions & filters" followed by "filters" looks confusing/redundant

[sedubois]

There could be a warning when viewing the old v2 documentation, with a link to go to the v3.

For example when viewing this: https://docs.avohq.io/2.0/custom-fields.html

There could be a block at the top saying "You are viewing the documentation for Avo 2.0 which is in maintenance. Click here to view the Avo 3.0 documentation."

BTW such v2 documentation comes up in search engines instead of the v3 for some reason. Perhaps something to be tweaked in the website's robots/SEO/meta tags config?

[sedubois]

As mentioned in Discord, the search feature could be improved.

[adrianthedev]

As mentioned in Discord, the search feature could be improved.

What would you like to see improved? The user interface, the searching, matching, speed?

We use Algolia doc search which comes baked in with vitepress and needs less effort from our part. We'd like to consolidate our efforts to building the framework, but will take in any improvements from the community. The docs repo is open source.

[sedubois]

the search feature could be improved

What would you like to see improved?

@adrianthedev let's take the example of finding how to scope items in a association field. As I want to learn how to configure that, I go to the documentation and will want to search for an option that applies to the field DSL, so I went to the field options documentation page. The very name of that page makes it clear that whatever the field DSL supports as options should be listed on that page. However I went through that whole page and found nothing about scoping the field to only include specific records. I also hit Cmd-F on the keyboard and searched for "scop" but nothing relevant came up either. The page should list and hyperlink to options that are described elsewhere in the docs (in this case, the option I was looking for was "attach_scope").

Also broken link in the docs:

https://docs.avohq.io/3.0/search.html#enable-search-for-a-resource

In this block, you may configure the search however strict or loose you need it. Check out ransack's search matchers to compose the query better.

The Ransack README has no section with hash #search-matchers.

[sedubois]

Actions documentation: https://docs.avohq.io/3.0/actions.html

the code syntax could be simplified with the one suggested by Paul: https://discord.com/channels/740892036978442260/1222107435351805973/1222115078187253780

Before:

def handle(**args)
  query, fields, current_user, resource = args.values_at(:query, :fields, :current_user, :resource)
  # ...
end

After:

def handle(query:, fields:, current_user:, resource:, **args)
  # ...
end

[adrianthedev]

Would you be able to open a PR with that suggestion? https://github.com/avo-hq/avodocs

[sedubois]

Would you be able to open a PR with that suggestion? https://github.com/avo-hq/avodocs

FYI @adrianthedev this is waiting for a review: https://github.com/avo-hq/avodocs/pull/184

[Paul-Bob]

Thank you @sedubois, we'll have a look

[sedubois]

The map documentation mentions "you need to add the map_view class attribute" but the code snippet below then uses self.map.

Also, the doc does not mention that the gem mapkick-rb is required (otherwise error undefined method js_map' for an instance of Avo::Index::ResourceMapComponent`).

https://docs.avohq.io/3.0/map-view.html

[adrianthedev]

@gabrielgiroe1 can you please ensure the map example is valid?

[github-actions[bot]]

This issue has been marked as stale because there was no activity for the past 15 days.

[github-actions[bot]]

This issue has been marked as stale because there was no activity for the past 15 days.

[github-actions[bot]]

This issue has been marked as stale because there was no activity for the past 15 days.

[github-actions[bot]]

Closing this because there was no activity for the past 15 days. Feel free to reopen if new information pops up ✌️