Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update copy-delivery.md #2388

Closed
wants to merge 7 commits into from
Closed

Update copy-delivery.md #2388

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
fb15209
Update copy-delivery.md
srhhnry Sep 20, 2024
a250494
chore(pre-commit): autofix run
pre-commit-ci[bot] Sep 20, 2024
c05c251
docs(copy): update Engineering responsibilities
machikoyasuda Sep 23, 2024
c35a3f3
Update docs/product-and-design/copy-delivery.md
srhhnry Sep 25, 2024
1268701
Update docs/product-and-design/copy-delivery.md
srhhnry Sep 30, 2024
8fc19f7
Update docs/product-and-design/copy-delivery.md
srhhnry Sep 30, 2024
b485100
Update docs/product-and-design/copy-delivery.md
srhhnry Oct 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 32 additions & 16 deletions docs/product-and-design/copy-delivery.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,34 +10,50 @@ Translation strings include all application copy, including:
- In-line link URLs
- Error messages (like [no script](https://github.com/cal-itp/benefits/blob/main/benefits/core/templates/core/includes/noscript.html), [no cookies](https://github.com/cal-itp/benefits/blob/main/benefits/core/templates/core/includes/nocookies.html) warnings)

## Cal-ITP Benefits Application Copy
Developers create and update `django.po` message files for each supported language from copy created and implemented by Design and Product. Design and Product use the tools Figma, Ditto, and Crowdin to craft product copy, manage all copy and variantions of copy (e.g. agency-specific copy or Spanish translation copy), and translate copy.

The human-readable version of the English and Spanish translation strings for the application are delivered to Design and Engineering by Product, and live at this link: [Cal-ITP Benefits Application Copy](https://docs.google.com/spreadsheets/d/1_Gi_YbJr4ZuXCOsnOWaewvHqUO1nC1nKqiVDHvw0118/edit#gid=0).
## Tools used in Cal-ITP Benefits Application Copy

By tabs:
### Figma

- `EN-USA` tab contains all copy for English, which each row representing a page. This copy uses a sample agency, called California State Transit (CST) with an Agency Card. This copy is used in Figma.
- `forTranslation` and `All Agencies` tab contains the English and Spanish translation side by side, with agency-specific copy.
Figma is our primary design tool and is the source of truth for all design decisions, concepts, and directions for the Benefits app and all Cal-ITP sites. We have Figma Organization which includes developer mode, version history, and branching–a tool to explore new design directions.

The development team prefers not to have admin or editor capabilities so as not to accidentally interfere with any designs. Currently there is no formal process within Figma for handoff. Instead handoffs occur over the course of two meetings, a review of the designs and then what we call “issue-fest,” or a chance for developers to create Github issues while designers can weigh in and answer questions.
Copy link
Member

@machikoyasuda machikoyasuda Sep 23, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The development team prefers not to have admin or editor capabilities so as not to accidentally interfere with any designs. Currently there is no formal process within Figma for handoff. Instead handoffs occur over the course of two meetings, a review of the designs and then what we call “issue-fest,” or a chance for developers to create Github issues while designers can weigh in and answer questions.
The development team prefers not to have admin or editor capabilities so as not to accidentally interfere with any designs. Currently there is no formal process within Figma for handoff. Instead handoffs occur over the course of two meetings, a review of the designs and then what we call “issue-fest,” or a chance for developers to create GitHub issues while designers can weigh in and answer questions.

@srhhnry

  • Aren't we gonna use the Ready for dev feature in Figma for handoff? At handoff or issue-fest, not sure which, Design will also Merge the current Figma Branch into the main Branch, so that also indicates a new status.
image
  • If anyone (Product, Engineering) has concerns about copy, should they put a comment on Ditto, on Figma, or some other way?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Yup, I can write the Ready for Dev element in. I'd say we don't have a hands off approach with Figma though, and we rely on meetings/verbal communication over asset deliverable. Not sure when merging should happen. This time it happened after issue-fest (same meeting as hand-off), but I can see where merging after hand-off, and any updates, but before issue fest would be best. That way there's still a chance to see if there are any mistakes on the board and correct in real-time, as merging is a bit of a manual process.

  • My strong preference for comments is to have them in Figma. But I think we should note this is subject to preference and can change based on team dynamics.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm re-reading this section and I realized one thing that is confusing me: Instead handoffs occur over the course of two meetings, a review of the designs and then what we call “issue-fest,” or a chance for developers to create Github issues while designers can weigh in and answer questions.

Maybe instead of having 2 meetings that are both called handoffs, the last meeting should be The Hand-Off. And the first meeting is a Design Review. I think we can be explicit in our definition of what a handed-off design looks like.

A handed-off design means:

  • The Figma file is fully synced with copy from Ditto and CrowdIn.
  • The copy is production-ready in English and Spanish.
  • The new designs in Figma are marked as "Ready for Dev".
  • The new designs in Figma, which were previously in a branch, are now merged into the main branch.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If your preference is for comments in Figma, then we can make that the policy. You can note that all comments on copy or design should be made in Figma, and that all comments need to be submitted by the Hand-Off meeting. No comments should be added after the Hand-Off meeting ( as in, engineers cannot ask design to change anything after hand-off. that would be a new design process ).


The dev team and design largely collaborate on designs through Slack and comments directly in Figma. Design aims to address Figma comments as soon as possible or within one day.

### Ditto

The human-readable version of the English and Spanish translation strings for the application are delivered to Product and Engineering by Design, and are managed in the Ditto application. [Cal-ITP Benefits](https://app.dittowords.com/projects/65e119db3f806ee92198378a/page/5766:22626).

Ditto is our copy management system for Benefits and the Cal-ITP sites. It syncs directly with Figma and uses many of the same conventions found in Figma, including components and variables (therefore, it is important to be specific when referring to a Ditto component or a Figma variable).

The Benefits project within Ditto is fully synced with Figma. Product and design may use either Figma or Ditto as their source of truth on copy, though it is recommended that Developers use Figma for all final copy. Compiler is considering using the GitHub integration that comes with Ditto, but has not formally integrated Ditto into their workflow as of yet.

In the Benefits project, all of the text has been componentized. Agencies are represented in the text as variants on components. Languages are also represented in the text as variants. Currently Benefits has two languages: English and Spanish. English is the assumed default in the copy in Ditto and Spanish is a variant. There are variants within Ditto that include both an agency and Spanish, such as MST-Spanish.

### Crowdin

Crowdin is our translation platform. We use iBabbleon to provide our translations. With very simple translations (or more complex if you are fluent or native in the language), Compiler team members can translate the strings of text directly in the Crowdin platform. For anything above our language skills, Design contacts Salim at iBabbleon and ask for the new files to be translated once the language files have been synced from Ditto to Crowdin.

## Copy delivery process responsibilities

### Product

- Engage with product stakeholders to get the information necessary for copy writing.
- Engage with copy writers to get the English language copy drafted, proofed and ready for design.
- Engage with client editorial/communications team to ensure English language and Spanish language copy are edited according to client style guides.
- Engage all necessary stakeholders to get English language copy approved and ready for design.
- Compile copy in [Cal-ITP Benefits Application Copy](https://docs.google.com/spreadsheets/d/1_Gi_YbJr4ZuXCOsnOWaewvHqUO1nC1nKqiVDHvw0118/edit#gid=0), ready to be used by Design, so Design can sync the spreadsheet to Figma.
- Engage with the translation agency, [iBabbleOn](https://ibabbleon.com/), to get Spanish translations ready for Engineering.
- Transfer translations from iBabbleOn to the spreadsheet, in proper format.
- Ensure English and Spanish copy is ready for Engineering.
- Collaborate with Design on copy writing.
- Help verify English and Spanish copy is ready for Engineering.

### Design

- Sync copy from [Cal-ITP Benefits Application Copy](https://docs.google.com/spreadsheets/d/1_Gi_YbJr4ZuXCOsnOWaewvHqUO1nC1nKqiVDHvw0118/edit#gid=0) into Figma.
- Ensure the string is in the appropriate column (e.g. `Subtitle`, `ButtonLabel`)
- Collaborate with Product on copy writing.
- Draft, proof and ready the copy for review in Figma and Ditto.
- Engage with client editorial/communications team to ensure English language and Spanish language copy are edited according to client style guides.
- Ensure copy is synced between Figma, Ditto, and Crowdin.
- Engage with the translation agency, [iBabbleOn](https://ibabbleon.com/), to get Spanish translations ready for Engineering.
srhhnry marked this conversation as resolved.
Show resolved Hide resolved
- Deliver production-ready copy, with Spanish translations, to Engineering at Design Hand-Off meeting via a synced Figma file in the main branch.

### Engineering

- Use copy from the English and Spanish language tabs of the spreadsheet, and turning it into code in `django.po` message files. Developer-specific instructions in the [Django message files technical documentation](../development/i18n.md).
- Ensure the messages accurately reflect the spreadsheet and Figma designs.
- Use copy from Figma, properly synced with Ditto, into code in `django.po` message files. Developer-specific instructions in the [Django message files technical documentation](../development/i18n.md).
- Ensure the messages accurately reflect Figma/Ditto.
Loading