Communication strategy

[kenbot]

I think the website, scaladoc, code/variable naming, import interface and compiler error messages all have to form one coherent, clearly stated communication strategy for 3.0 release. They all have to make sense with respect to each other, not just themselves.

[julien-truffaut]

Yeah I completely agree. I think what is important is to define a pattern, e.g. select a few features/optics/methods and write the sort of documentation we expect to get for the rest of the library.

For example, it would be great to create a section on the website documenting all the Optics Builder methods. This would include code example, is it available via Focus macro, conditions etc

some

Description	Zoom into an Option but only if it is a Some
Available	All Optics, ApplyOptics and Focus
Example	Focus[User](_.address.some.streetNumber) .replace(4) ...

Then we could reference this documentation in the code

/**  Description | Zoom into an `Option` but only if it is a `Some`
 @see www.optics.dev/optics-builder#some
*/
def some[A1, B1](implicit ev1: A =:= Option[A1], ev2: B =:= Option[B1]): PPrism[S, T, A1, B1] =

[julien-truffaut]

@kenbot do you have an idea how should we do this and communicate about it?

[kenbot]

I think my ideas are pretty aligned with yours. I'd say:

Have "onion rings" of documentation levels, where each level n need not know anything about n+1. Something like:

• Level 1: Focus macro features, basic examples. Reusable optic use case, single-use applied use case.
• Level 2: Monomorphic optic family, hierarchy, composition table, operators, relationship to what they know in Focus, bulk auto-generation of optics, advanced use cases that Focus isn't enough for.
• Level 3: Polymorphic usage, STAB, creating new custom instances of optics. Use cases requiring polymorphism. Cats integration