Working with Clients¶
We have many clients, and not all of them are covered in this handbook. If you're encountering a new client for the first time, you're encouraged to visit our CRM and read up on their entry. Each entry in the CRM has an 'updates field' that you can expand which contains an initial briefing on that client.
When a new client signs a contract with us, the Business Development Representative will post an initial 'Client Briefing' with this template, which has been made into a separate page so its formatting can be copy-pasted. Time for this work should be logged to whatever epic we start for this client.
Scope of the Briefings¶
The briefings should contain information that is useful to all (or nearly all) of their epics, as well as other background and contact information that may be helpful to know. Details relevant only to one epic should be kept in the relevant epic ticket, and that epic ticket should be linked in the briefing. If an epic is completed and not likely to be especially important for understanding the current needs of the client, it can be removed from the listing.
Information about clients changes over time-- which projects we have, important links, points of contact-- all of these can change, as well as background knowledge. The purpose of a briefing is to allow a developer to get up to speed quickly on a client's most important information.
To keep things up to date, Client Owners will write an update to the CRM entry for each meeting or signficant interaction they have with the client. Once a sprint, they will consolidate the updates to the most important points and recreate the initial briefing with the most up to date context. Client owners should log time spent maintaining briefings to whatever epic they most commonly use for meetings with this client.
Keeping this client briefing information succinct and informative helps new team members get up to speed quickly. Think carefully about what information from recent discussions will be relevant in the long term, and what can be discarded. See the 'Scope of the Briefings' section above for points to consider.
Communicating with Clients¶
We prefer direct communication between our team members and clients. There are a few things to keep in mind, based on medium and situation.
Client owners are the point person¶
Client Owners manage the relationship with the client and help them with ongoing and new initiatives. They keep an eye on epics for that client and keep the briefings updated, as mentioned above.
They're good to include by pinging on conversations with clients for anything which may have larger context/impact than the task you are currently on, so that they can have visibility and the opportunity to offer input.
When clients write to you via email, always CC
help+client@ in your replies, where
client is the name of the client's mailing list label, such as
campus. If you're unsure of the client's mailing list label, ask the client owner. This allows any developer to have record to refer back to as needed. If you are not the client owner, CC them (and the epic owner as necessary) as well to make it clear you're specifically looping them in.
Many of our clients have their own issue trackers. You can (and should) talk directly with your contact on that ticket about any questions you have about the requirements, or if you need the client to review your work. If you get stuck from a technical perspective, consult with fellow team members instead.
We work with edX all the time, in various ways - but this document is specifically about how to work with edX as a client, when they're paying us for the work. edX calls this "Blended Development", because the team is a blend of OpenCraft and edX people.
An overview of when, why, and how edX does "blended development" is on their wiki at Blended Development Runbook and Best Practices.
- Before opening a pull request, review the Blended PR Workflow which explains the procedure for opening a PR on any blended project. (In addition to the usual PR process that we follow on all projects.)
- Remember to default to public communications. This is an open source project and generally most of the aspects of blended development can be public - so default to discussing and documenting things on public Confluence pages, Jira tickets, ADRs, Discourse threads and public Slack channels.
- If that doesn't get enough attention or timely response, then ping on synchronous and/or private tools, linking to the public question.
- Slack is one of edX's major communication channels and we should not be hesitant to ping people on it, in the same way we try to reduce synchronous pings on Mattermost within OpenCraft.
- Note: understand that edX has two Slacks: their internal Slack (which we cannot access directly), and the Open edX Slack (which we do have access to). Most edX employees are on both, and some channels are shared between both Slacks, such as the #edx-shared-opencraft channel.
- Some projects we do with edX have their own public Slack channel on the Open edX Slack channel, which should be documented on the project's confluence page.
- If you don't have access to the #edx-shared-opencraft channel, ask someone to invite you. It is OK to share some non-public information on this channel, as it is private to OpenCraft and edX.
- Slack should be treated as ephemeral, so if it's used for making any decisions impacting the project, those decisions should be documented in Confluence right away.
- Iterative development and regularly shipping PRs to production is the expectation; if your PR is languishing without a review for more than a week, please considering that a big problem that you need to solve immediately. Ping people and escalate as needed.
- If newcomers are working on tickets for edX, they should first submit their PR to an internal fork (OpenCraft fork) and get it reviewed, and only submit it upstream once the reviewer has approved it.
How to escalate an issue / how edX will escalate an issue¶
If you are blocked or have an urgent problem (or edX is in that situation), the procedures for escalating issues with each other are documented in Confluence at Blended Provider Status Pages: OpenCraft: Escalation Path ; also see the project page for each blended project, to see who the "edX lead" is as well as any project-specific escalation instructions.
How to mention people on the edX Jira¶
Due to an annoying bug, you may find that you are not able to ping people on the edX Jira. There used to be a workaround within Jira but it is no longer available. Until this bug is fixed, please do the following after commenting on the edX Jira:
- Join the edX Slack instance.
- Find the person you want to ping and let them know you've updated the ticket, with a link to your comment.
- If they ask why you are pinging, point them to this section of the handbook, which is publicly available.