POLISH uses a shared Slack channel in client projects to keep records of requirements, decisions, and launch notices. The value of a shared channel is keeping decisions in a place visible to both sides. That value depends on usage rules that have been agreed in advance. A channel also interrupts work, and POLISH's approach accounts for the cost of those interruptions.
How research views shared channel use in software teams
Stray et al., 2019 used a case study to examine how a distributed project used Slack. The benefits were greater transparency, team awareness, and informal communication. The challenges included language problems, overuse of private messages, and uneven levels of activity among members. The authors recommend that teams agree on usage guidelines for the tool. This is a case from a single project.
Lin et al., 2016 is a preliminary study in short-paper form. It reports that development teams use Slack at three levels, personal, team, and community, and that in some cases it replaces email. The subjects were development teams themselves.
Storey et al., 2017 surveyed 1,449 GitHub users and compiled the communication channels developers regard as essential to the work, along with the challenges of using several channels at once. Respondents lean toward open source and developer communities.
POLISH turns its channel practices into concrete rules. For example, anything the design files do not cover is raised directly in the channel, and all reports go into the same thread. The sections below describe these rules by project phase.
The shared channel is created at the start, and members join by phase
POLISH creates the shared channel at the start of a project and then invites the client's project contacts, front-end developers, and back-end developers in stages. Before development begins, POLISH changes the channel so that only invited members can see it.
Once a front-end developer joins, POLISH immediately opens access to the front-end code repository and provides documentation for the key configuration APIs. New members receive the needed resources right from the start. POLISH asks the front-end developer to decide the branching rules, whether by feature or by developer. The person actually writing the code decides how collaboration works.
Fields and statuses of the issue list
Reports posted in the channel are converted into items on the issue list, which turns the reports into trackable records. The list has six fields.
| Field | What is entered |
|---|---|
| Name | Starts with the date (year, month, day) followed by a short description, which helps with sorting and tracing |
| External | Marks whether the report comes from a first-line user on the client side |
| Completion date | Entered after the production site is updated |
| Internal status | Pending, tested and ready for production, completed, canceled, needs review |
| Owner | POLISH engineering staff |
| Requester | A project member on the client side, or POLISH itself |
The flow is shown in the diagram below. The requester creates an item, and the owner claims it, fixes it on the test site, and changes the status to tested and ready for production. After the production site is updated, the owner marks the item completed and enters the completion date. Every status change stays on the list, so the requester can see how far an item has progressed without asking separately.
Based on the issue list POLISH actually uses. Items that will not be done are marked canceled, and items that need rechecking are marked needs review.
Quality checks during development follow the same logic. When project members find something in the admin interface that does not work smoothly, the problem is added directly to an online board. After each round of discussion, POLISH syncs the newly added optimization items to the board and the design files, and posts that round's list in the channel with an owner marked for each item. When a developer finishes an item, the card moves to the to-be-confirmed column, and a project member on the client side is asked to confirm it. Every report has someone who claims it, and every completed item has a confirmation step.
After launch, POLISH likewise receives client reports through the issue list. The service itself is described in long-term maintenance and platform development. Periodic checks and maintenance reports are covered in routine maintenance after launch, and the overall rhythm of meetings, issue lists, and launch checks is covered in recurring meetings, issue lists, and launch checks for annual projects.
Changes and launch notices are written out item by item
When the design files are updated, POLISH posts the adjusted items as a list in the channel, for example menu items, the font and style of the navigation bar, and page content, and schedules a time to walk the front end through the details. When the design files have multiple pages, POLISH states in the channel that the component overview page is the reference and asks the designer to bring the remaining pages into line with that version. The designer confirms the update in the channel. The aim is to prevent the front end from seeing different versions of the design.
For changes that must be made on several ends at the same time, POLISH lists the items in a single message and marks which end handles each one. Where useful, images and a code lookup table are attached, for example interface codes that correspond to page names. The message points out in advance which existing features may be affected and notes that anything missing should be discussed next. The engineering side replies to confirm the scope of impact and that existing workflows are unaffected, and then releases the update. Examples include renaming and merging the terms page, adjusting paragraph styles, and adding a file section for users to download. When several ends change at once, items are less likely to be missed, and the change can be traced afterward.
Putting several changes into one message also reduces interruptions. In the experiment reported by Mark et al., 2008, interrupted work was completed in less time with no difference in quality. People compensated by working faster, at the cost of more stress, frustration, time pressure, and effort. The experimental tasks were performed in a laboratory. The study supports the point that notification interruptions carry a cost. POLISH groups a batch of changes into one message so that the reader can take it in all at once.
Before and after each deployment, POLISH tags the client's project contacts in the channel. Before deployment, the message states the expected completion time. Afterward, it states that the update is done and that content can be published. When the client is still editing data, the reply says that some working time is needed. Deployments and content updates therefore leave a time record in the channel.
In the early period after launch, report volume is high, and a single entry point and a predictable update rhythm are needed. POLISH uses the launch announcement post as the central place for reports, and any problem the client finds on the production site can be posted in that one thread. POLISH releases updates in batches according to impact. Problems with screens and wording are updated first, and the remaining issues are grouped into later batches. POLISH reports the progress of each batch, and whether it is folded into a production update, in the same thread. The client keeps adding screenshots and written descriptions to the thread, and POLISH marks each item as in progress or handled.
When an approach involves trade-offs, the options and costs go in a discussion thread
When an approach involves a trade-off, the responsible engineer lists two options and the cost of each in the discussion thread. The owners of the data and the interface state a preference, and work begins only after the product side approves. Items not yet settled are marked to be changed once the detail meeting has confirmed the outcome.
Per-page required-field validation is one example. One option has the front end check only whether a field is filled in, with a uniform message. The other adds a separate interface for single-page validation. The required fields had already been settled in discussion and were unlikely to change, so intercepting at the front end was easier. The drawback is that later changes require edits on both the front end and the back end. After the product side approved, the front-end interception option was adopted and a new version was released. Paragraph styles involve a similar trade-off, between switching to an editor package and keeping plain text.
During development, POLISH asks the front end to raise anything the design files do not cover directly in the channel, so that the designer and POLISH learn of it at the same time and avoid waiting on each other. Dropdown options for shared styles can be viewed on the component page. It was agreed from the start that the option data comes from the back-end API. Changes to options are reported to the back end, and missing data can be confirmed directly in the group. The aim is to shorten the back-and-forth and to make the data source clear later, during maintenance.
Stray et al., 2019 list overuse of private messages as one of the challenges. A question written in the channel is visible to the designer, the front end, and POLISH at once, with no need to ask each person by private message.
Source records for requirements, entry points, and meeting minutes sit outside the channel
Requirements and to-do items use tracking cards as the source record. Client members request account changes and leave comments on the cards to report problems, and POLISH updates the status on the card and replies in the channel. The channel is for reminders and discussion, and the card keeps a traceable processing status. When a client member cannot comment in the card system, the engineer first checks whether it is a permissions problem.
Environment entry points and progress are kept on shared canvases inside the channel. POLISH pins two shared canvases in the channel. One holds the front-end and back-end entry points of the production and test environments, and the other tracks project progress. POLISH and client members keep updating both throughout the project. For handover and tracing, the two canvases are the single source record.
Agendas and minutes for recurring meetings are kept in shared documents in the channel, named by date. Client members post an agenda preview before the meeting, and POLISH members go back to the document to add to it. When earlier material needs to be cited, it is placed in that meeting's minutes and POLISH is notified to retrieve it. Requirements and resolutions are therefore kept in one place that can be looked up, rather than scattered through conversations.
Meeting minutes are also posted in the channel, with an owner and a to-do for each item, for example confirming the data content or the schedule for document handover. Lower-priority items are marked as such in the minutes, and the members concerned arrange a time among themselves to discuss these items.
- Content that needs to be kept appears in the channel
- The source location is chosen by the nature of the content
- Requirements or to-do itemsTracking cardPOLISH updates the card and replies in the channel
- Environment entry points and project progressShared canvases in the channelPOLISH and client members update both throughout the project
- Agendas and resolutions of recurring meetingsShared documents named by dateThe agenda preview is posted before the meeting, and POLISH members add to it afterward
- An approach with trade-offsDiscussion threadOptions and costs are listed, and work begins after approval
Stray et al., 2019 recommend that teams agree on usage guidelines for the tool. The storage locations in the diagram are the guidelines POLISH follows in its projects. With each kind of content kept in one place, there is a single reference for lookup and handover.
When a shared channel is not a good fit
- Neither side has someone who checks the channel regularly. Messages simply pile up unread, and no one confirms the decisions.
- The project has a single delivery and little contact afterward. Email plus a list is enough.
- The client already uses a communication tool internally on a regular basis. Adding another channel increases the burden of using several channels at once. The rules for the issue list and source record locations still apply in that case, with the tool replaced by the one the client already uses.
What to prepare before starting
Before a project starts, POLISH confirms the following items with the client, one by one.
- The roster of members who join the channel at each phase and when each one joins, and the point at which the channel is changed to invited members only before development begins.
- The client's project contacts, who reply in the channel and are tagged before and after each deployment.
- The six fields and five internal statuses of the issue list, with both sides confirming the wording.
- Access permissions for the tracking cards, shared canvases, and shared documents, confirming that client members can comment and update.
- The channel's usage rules, for example raising anything the design files do not cover directly in the channel, posting reports in the same thread, and listing options and costs in the thread when an approach involves trade-offs.
To compare how vendors handle communication and records, see a software vendor scorecard and pre-contract checklist.
POLISH sets up the channel, the list, and the source record locations according to the project phase and the communication channels already in use. When useful, contact POLISH to discuss the communication rules and issue list for a project.
