Delete Developer roadmap from docs?

[stevepiercy]

@tiberiuichim you worked on the original document. Should we delete Developer roadmap? I think it is redundant to everything under Contributing to Volto, https://plone.org/why-plone/roadmap, and https://github.com/orgs/plone/projects/33/views/1.

[tiberiuichim]

@stevepiercy Maybe its name is wrong, but it's a valuable document. It's not intended to Volto contributors, but for "Volto project developers", for the integrators.

We can rename it.

[stevepiercy]

OK, let's improve it, so it has more value. It definitely needs to be updated and revised with current practices, including the monorepo. The bullet points of terms and phrases lack definitions or references, leaving the reader at a dead end.

Also, I don't know the difference between a "developer" and an "integrator". Can you elaborate?

[tiberiuichim]

@stevepiercy

developer = contributor to the github/plone/volto
integrator: someone who uses Volto for their own customer projects

The "Developer roadmap" page was created with the "integrators" as the target audience.

[stevepiercy]

I'd argue that both contributors and integrators are developers. A contributor develops Volto core, whereas an integrator uses Volto to develop solutions for their clients. Would those be agreeable definitions?

[tiberiuichim]

@stevepiercy Yes, but it seems that the term "developer" used in the Developer Roadmap document doesn't exactly pinpoint to the its intended audience. My idea when I created that document was to provide some sort of roadmap, to allow integrators to evaluate their knowledge level.

[stevepiercy]

I see. It sounds like this should be a reference document, per https://diataxis.fr/.

This also speaks to a larger issue of docs reorganization, specifically how do we direct each audience to the correct resource?

Frontend is the entry point. This page should have wayfinding directions for each audience. A heading should address each audience, and should be defined. Thus the reader knows which section applies to them.

This is probably already addressed in another issue, but to keep the momentum, here's what I suggest to add to Frontend.

---

Get started

Introductory text for the following subsections.

Contributors

Definition text here

• First-time contributors is a special type of contributor that needs more direction than any other type.
• Contributing to Plone
• Contributing to Volto

Integrators

Definition text here

• Developer roadmap

Users

Definition text here

• User Manual

Other groups?

---

Back to this page, right now it is buried deep and misnamed.

Suggested revisions:

1. Rename "Development recipes" to "Development".
2. Change title (and associated bits) to "Integrators".
3. Move under "Development". (This section itself might become a section in "How-to Guides" under Diátixis, but we'll deal with that later.)
4. Hyperlink existing text to relevant pages under Development and Contributing to Volto.
5. s/developer/integrator, and define these terms in the glossary.

This is a lot to digest. I'd appreciate your thoughts. We can also chat at the next Documentation or Volto meeting, or whenever you're available in Discord.

[stevepiercy]

@tiberiuichim I'd appreciate your thoughts on the above plan in #5730 (comment). @davisagli @sneridagh and anyone else, too.

[stevepiercy]

I started PR #5809 to address this.