Get documentation feedback from users

[xeniape]

A first idea from the Retro would be to try out some form of simple button to submit feedback about the documentation

Probably needs refinement

• Research the possibility of such a feature in our current setup
• Submit general feedback or per page?
• Where are the submitted feedbacks send to? How to read/address them?

[xeniape]

Saw this feedback form in the OPA documentation, which looked nice and simple. Posting for reference later.

[xeniape]

Refinement

Frontend

The common approach amongst Antora users seems to be to add a feedback submission form themselves as Antora does not provide anything like that. I tried out a simple prototype to test it out here: #147 and here stackabletech/documentation#833

Some screenshots of the prototype:

---

---

Backend

Didn't find a really good already existing solution for the backend to send the feedback submission to, but also didn't look too much into it to prioritize reusing things we already currently have for now or to have a discussion if someone can recommend something they know.

Possible solutions:

• Use Netlify Forms https://app.netlify.com/projects/stackable-docs/forms
  • Tried this as part of the prototype
• Find an already existing solution
  • Found only non-fitting or proprietary so far, through article below found https://github.com/allenarduino/formgrid
• Build a backend ourselves (maybe in the Stackable portal?)
  • Didn't try this, would only tackle it if it gets prioritized to do

The Netlify Forms solutions might also be a good first try to get a feel for the feedback submission frequency and if it helps us improve the docs etc. Maybe, depending on the feedback frequency, this solution might also be enough for the beginning.

---

This is how the current prototype information would appear in Netlify Forms:

There is also the option of sending E-Mail / Slack notifications on submissions.

---

Regarding the Netlify Pricing: Not exactly sure how much the cost would be in Netlify, the docs say:

For legacy plans, forms pricing is metered on a per-site basis and scales with usage. [placeholder to legacy pricing plans] For paid plans, Forms pricing is metered on a per-site basis and scales with usage. When usage reaches a level limit, the site will automatically upgrade to the next level or package. Free tier accounts are also metered based on usage and have a limit.

Was hard to find any information in Netlify itself where this limit is, but https://formgrid.dev/blog/netlify-forms-is-getting-expensive-here-are-the-best-alternatives-in-2026 mentions it being 100 form submissions per month. Which is not much in the long run but maybe for testing purposes it's okay. I'm not sure about the automatic upgrade though and what that would mean for pricing / the account.

---

Actually through the article above I stumbled upon https://github.com/allenarduino/formgrid while writing. Maybe that's something to explore for the implementation as a backend.

---

Also I'm not sure which submissions really count towards the limit for pricing. Because there are verified submissions and spam submissions. The prototype from this refinement also shows the use of a honeypot field for spam prevention.

The prototype also does not include sanitization. According to https://docs.netlify.com/manage/forms/submissions/#automatic-sanitization it should be included, but when testing it, it didn't seem so. However, that might be because, for the submission itself the prototype does not use Netlify automatic detection of fields, because the selection of the Yes/No buttons required a customized request. But a proper implementation could be looked into during the actual implementation.

Summary

The addition of a submission form itself should be fairly easy and was already tried out during the research as a prototype. The next thing would be deciding on a proper backend to send the submissions to, if that's either something small/simple for a try-out phase first like Netlify Forms, a proper backend already existing somewhere (any suggestions?), or implementing something ourselves.