sharing components back to pubsweet - outcome of pubsweet meet
At the latest pubsweet meet, there was an opportunity for each xpub team to demo their app for the other teams. These demos highlighted that many teams had created components which would be useful to share back to pubsweet but hadn't done so yet.
There are multiple reasons why components are not shared back to pubsweet immediately:
- Lack of awareness/visibility
- unsure whether the component is needed by anyone else or is specific to your own app
- unaware of the other use cases that exist & therefore which alternative implementations need to be supported before a component is shareable vs too context-specific
- the Component Library, which describes all pubsweet components, is out of date
- Time constraints
- creating a component for your use case takes less time than creating a generic component that works for more/all use cases, so devs often feel that a component is not 'ready'/'finished" (i.e. in a shareable state)
- delay in waiting for pubsweet's package to be published before being able to use the component in your own app - in your own repo it only needs to make it through the PR process and then its usable, whereas in pubsweet there is an extra step involved
- dependency on 2 different PR approval processes & merges (app-level & pubsweet-level) make it more attractive to build in-app first and worry about sharing back later
At the pubsweet meet, we begun by tackling the lack of awareness / visibility issue.
Problem - lack of awareness
- We can search through pubsweet's styleguidist, to see if a React component has already been created, but we can't see if the component we want has already been created by another xpub team.
- Need a common record of all pubsweet components which remains up to date with the codebase(s)
- Discussions about component design/implementation are split across the design repo & the pubsweet repo. We don't have a clear way of collaborating on ideas for components & a lack of documentation means that people follow different processes.
- We don't know each others' contexts well enough to design components that are reusable within each other's apps.
Solution - greater visibility
- Create a single source of truth for all components across pubsweet & the various xpub apps
- Immediate: The working group has compiled a list of existing components that aren't in pubsweet
Short term: Each team adds
styleguidistto their project if they haven't already, deploys it for other teams to browse & adds the link to the List of components wiki
- Europe PMC
- Long term: We are looking into the creation of a centralised styleguidist deployment, so that teams don't need to look in multiple places. This was started by Rich on day 2: https://gitlab.coko.foundation/pubsweet/styleguide
- Unsure how to keep Component library docs up to date. One suggestion: create markdown file next to each component & use styleguidist to show more than just UI components. Separate issue raised #409
- When you've identified that you need to create a new component, first raise an issue on the pubsweet repo
- Working group to raise issues for each of the existing components that need to be shared back
- Create documentation on this contribution process
- Learn each other's contexts via regular demos, which will be recorded for dissemination
- Schedule a regular time
- Decide on number of participants per team required (note: people demo-ing need to be able to explain domain context & implementation choices)
- Post recorded videos somewhere & document this location
- Each team deploy a sandbox environment of their app, for other teams to be able to click around to their hearts content & play (is this realistic/do-able?)