Documentation Pain Points Thread

[deviprsd]

I think having one place for now to track documentation pain points in a more informal way can help surface those up quicker. Then these can be tackled a lot more easily as we can gather them in a more public space than discord. All the information is siloed in discord and is hard to sort through or even lost with time.

General suggestions for this thread is,

• Describe your task and how did you went about looking for the documentation?
• What concepts were not clear of that documentation?
• Did you get your concepts cleared and what were they?

Use sub-comments sparingly unless it is related to a PR or additional information that can be further enhance the concept. Use reactions to provide additional context on what could be prioritized.

[deviprsd]

Ash.PubSub

• I was trying to find a way to enable pubsub after database operations, leading to https://hexdocs.pm/ash/pub_sub.html (pretty thin)
• In discord I found these information on how to enable them

you need to add the notifiers: [Ash.Notifier.PubSub] to your use Ash.Resource statement

pub_sub do
    prefix "attendance_record"
    module MyAppWeb.Endpoint

    publish_all :create, ["created", [:id, nil]]
    publish_all :create, ["*"]
    publish_all :update, ["updated", [:id, nil]]
    publish_all :update, ["*"]
    publish_all :destroy, ["destroyed", [:id, nil]]
    publish_all :destroy, ["*"]
end

Realworld example:

• https://github.com/team-alembic/realworld/blob/main/lib/realworld/articles/resources/comment.ex#L30-L36
• https://github.com/team-alembic/realworld/blob/main/lib/realworld_web/live/article_live/index.ex#L25-L28

[deviprsd]

Ash.Type.*

• Documentation isn't very clear on it, but the properties mentioned in it are not part of the Attribute DSL but part of the contraints DSL.

For example, https://hexdocs.pm/ash/Ash.Type.Map.html

attribute :form_config, :map do
    description "Form dynamic labels"
    allow_nil? false

    constraints fields: [
                  amount: [
                    type: :integer,
                    constraints: [
                      max: 10
                    ]
                  ],
                  currency: [
                    type: :string,
                    allow_nil?: false,
                    constraints: [
                      max_length: 3
                    ]
                  ]
                ]
end

[dmitriid]

Ash.Authentcation

It would be nice to have an overview of all the steps needed to take before diving into them. Because there are quire a few steps, and as you scroll through the guide you may get completely lost.

As an example:

To let users authenticate with a password, we'll need the following:

• Create a user resource with the password startegy
  • Depending on the functionality, we may need to create additional modules to handle tokens and secrets
• Set up an AuthController to handle authorisation successes and failures
• Set up routes
• Set up session

---

Additionally, it is entirely unclear how to override the aut-generated HTML templates for Ash.Authentication