Branding/documentation best practices for new C++ FIDL bindings

[Yifei Teng]

Hi,

The FIDL team is about to launch a better version of the C++ bindings, growing it from LLCPP, and intending to replace HLCPP in the long term. The bindings, tentatively named "New C++ bindings" would be published to the SDK, which means users will have a choice to use either that or the existing HLCPP, which is currently the only SDK FIDL bindings and used in onboarding guides. We'd like to encourage use of the new C++ bindings since it offers various benefits. Our first plan is to start at the LLCPP tutorial pages, and rename that to "New C++". Then we'd add more content describing the features that we've built on top of LLCPP.

Docs folks: we'd love to hear suggestions and ideas for branding and messaging so that users don't get confused when these bindings exist side by side. Are there things we could write or practices we could follow so that users more easily understand which kind of C++ bindings they are using? We'd like our docs to mesh well with higher level documentation strategies you may have in plans too.

Cheers,

Yifei

[Ben Lawson]

When will the old HLCPP bindings be deprecated? Should we plan to migrate our code to the new bindings soon?

--
All posts must follow the Fuchsia Code of Conduct https://fuchsia.dev/fuchsia-src/CODE_OF_CONDUCT or may be removed.
---
To unsubscribe from this group and stop receiving emails from it, send an email to docs-discuss...@fuchsia.dev.

[Yifei Teng]

There's no concrete timeline for deprecation and HLCPP would remain fully supported while we circulate a RFC to socialize the details.

[Nick Van der Auwermeulen]

Hi Yifei,

Thanks for reaching out.

I am wondering if we should use a similar approach to what was done for Components, where components v1 became "Legacy components" and components v2 just became "components". I am thinking it would make more sense that moving forward the new C++ bindings just be called "C++ bindings" which would avoid the future question of when do these bindings stop being "new". We could then rename the existing bindings as "Legacy bindings".

As for deprecating documentation, I put together a playbook of how we can show our readers what is deprecated and how to clearly (for a user) differentiate between the latest docs vs docs that are starting to be deprecated.

Yifei, are you also envisioning a migration guide to get users to adopt the new bindings?

Additionally, we can add a caution banner, such as the components one to clearly call out the legacy bindings where they are documented.

Adding +Dave Smith for his ideas on how to integrate this new content with the Fuchsia bootcamp and +Chris Holguin and +Matt Hamrick  who may have some thoughts as to how to tie this in with their work on FIDL samples/guides.

If it helps, we could also set up a sync to formalize a strategy. 

-Nick

[Yifei Teng]

On Fri, Jun 24, 2022 at 6:55 PM Nick Van der Auwermeulen <nickv...@google.com> wrote:

Hi Yifei,

Thanks for reaching out.

I am wondering if we should use a similar approach to what was done for Components, where components v1 became "Legacy components" and components v2 just became "components". I am thinking it would make more sense that moving forward the new C++ bindings just be called "C++ bindings" which would avoid the future question of when do these bindings stop being "new". We could then rename the existing bindings as "Legacy bindings".

+100. The only blocker IMO is that the new bindings are not yet widely available. When consulting the component leads their main suggestion was to avoid marking things legacy/deprecated until the new thing is 100% ready. We're planning to build out support for the new C++ bindings in all customer repositories over Q3, and aftering getting a bit of mileage in each I think that could be a comfortable time to deprecate HLCPP (and when the "new C++ bindings" is no longer "new").

As for deprecating documentation, I put together a playbook of how we can show our readers what is deprecated and how to clearly (for a user) differentiate between the latest docs vs docs that are starting to be deprecated.

Yifei, are you also envisioning a migration guide to get users to adopt the new bindings?

That makes sense.

Additionally, we can add a caution banner, such as the components one to clearly call out the legacy bindings where they are documented.

Adding +Dave Smith for his ideas on how to integrate this new content with the Fuchsia bootcamp and +Chris Holguin and +Matt Hamrick  who may have some thoughts as to how to tie this in with their work on FIDL samples/guides.

If it helps, we could also set up a sync to formalize a strategy. 

Having a sync would be great. Our primary desire in the near term is making the new C++ bindings widely available and fit docs nicely within the overall information architecture. Deprecating HLCPP is likely to come much later. We wanted to ensure that documentation and samples for the two flavors of C++ bindings could co-exist without creating user confusion.