Document and Share Project Outputs benefits

[chrisn]

The benefits listed in the Document and Share Project Outputs describe potential impacts of applying a design system ("reduce redundancy within code", "decreases the potential that your audience will have issues", "improves overall performance", etc) but don't address the requirement of this section, i.e., that "Everything produced [...] should be in an open format, well maintained, and curated in a common format (so everyone is working from the same model)."

Those benefits should be covered elsewhere in the document (and may already be covered, I'm still reading), and a list of benefits written that directly addresses the requirement of this section.

[AlexDawsonUK]

Thanks for this @chrisn. Agreed this should be re-written to match the Success Criteria. I'll get onto this.

[AlexDawsonUK]

As most of the existing benefits were related to design systems, I've merged them into 2.13. I've also as noted above re-written all of the benefits for 2.12 to be explicitly related to the guideline and SC. This will be reflected in the next draft.

[chrisn]

Where can I see the changes? There's no update in the commit history here.

[AlexDawsonUK]

The changes will be made available when the next draft is published (we go through several internal review processes for quality control so we don't simply commit changes to the master branch at regular intervals).

However, if you wanted a preview:

Environmental: Deliverables that are used in common, easy-to-understand formats will take less computer time to learn and adapt to the environment. As such, less energy will be spent trying to manage a project with emissions savings as a consequence.
Accessibility: Well-documented products will be accurately labeled and described, with accessibility features baked in by default rather than added as an afterthought.
Performance: Standardized elements across a product or service improve overall performance by reducing the time developers code (recreating the same thing). This will inherently reduce emissions considerably through the building of sustainable patterns.
Economic: Well-documented third-party projects that can be implemented with ease are likely to have fewer ongoing costs due to a lower need for maintenance support agreements with any suppliers.
Conversion: Using an open format, to which anyone can contribute to, will have a lower barrier to entry as there will likely be no cost involved in participation. Therefore it will encourage more individuals to play an active role in your project's future.

Feel free to provide any feedback below!

[chrisn]

I'd suggest adopting a process where changes are visible, e.g., on development branches - and PRs that can be reviewed by the community.

[chrisn]

Environmental - These claims seem tenuous at best.
Accessibility - Producing documentation may or may not lead to accessibility features being baked in, that outcome isn't guaranteed by following the guideline
Performance - Again, seems unrelated to the guideline. And includes a claim about emissions that should be under "Environmental"
Economic - Why the need for "third party" here? Don't these benefits also apply to entirely in-house development ?

[AlexDawsonUK]

@chrisn This is something I am actively exploring for sure.

We use a format called ReSpec and the final format (which everyone sees online) is exported into it's dependency-free HTML form. This would make merging changes into the main branch tricky. One solution I've been moving toward is to have the ongoing development document available as a separate concern to the finalized form, thereby it should allow both a DEV and FINAL draft version to be visible at all times (and allow individuals to contribute easier via pull requests). It's something I'm bringing up at this months meeting to hopefully get in place as soon as possible.

RE your feedback:

I agree that further work needs to be done on some of these so I'll redraft them though on your first point I will make this point:

If an individual spends less time in front of a screen, there are clear energy savings (whether a developer or a user). Being able to understand code, documentation, or other material provided in-house or by third-parties will take time and thereby, the less friction which occurs, and the less effort involved, the more savings in effort and energy. If it can be accepted as a matter of economy that simple systems save money, it should be by comparison relatively straight forward as a parable to identify that by association, emissions savings will also occur (even support costs have emissions).

[chrisn]

I think there are more systemic issues at play here, but we'll raise a separate issue on that.

[AlexDawsonUK]

If you have a list of benefits that you believe would best replace the existing ones, I'd be more than happy to include them in the next draft (we are all volunteers so your contribution would be very much welcome).

[AlexDawsonUK]

I've taken another shot at the listed benefits taking into account your above comments:

Environmental: Deliverables that are used in common, easy-to-understand formats will take less computer time to learn and adapt to the environment. As such, less energy will be spent trying to manage a project with emissions savings as a consequence.
Accessibility: Well-documented products should have accessibility features baked in by default rather than being added as an afterthought. As such, if a product does have these features and is open (reducing the barriers to entry) it will be more inclusive for your visitors.
Performance: Standardized deliverables across a product or service improve overall performance by reducing the time developers spend recreating the same thing. This will inherently reduce emissions through the reduction in time wasted, via efficiency savings.
Economic: Well-documented projects that can be implemented with ease are likely to have fewer ongoing costs due to a lower need for maintenance.
Conversion: Using an open format, to which anyone can contribute, will have a lower barrier to entry as there will likely be no cost involved in participation. Therefore it will encourage more individuals to play an active role in your project's future.

Hope this addresses the issue better!

[chrisn]

I think the only real benefit here is the Economic one, potentially also Conversion.

With Accessibility, I see you've rephrased this as a recommendation, but the Benefits sections should list the beneficial outcomes of following a recommendation, rather than setting new recommendations. I suggest that if a guideline has no effect in a particular category, then we can simply omit that category (as is done elsewhere).

[AlexDawsonUK]

I still think there is a solid case on the environmental benefits (however systemic and as part of wider variables it encompasses) for the reasoning based upon my earlier comments. However I accept that the performance and accessibility are less tenable so I'll remove them from the guideline on that basis leaving just the three in place.

[AlexDawsonUK]

I have made the changes within the specification, however as you have requested this issue remain open I will keep it this way for the moment. Once the next draft is published and PR's are available this issue can always be closed with any further changes directly made through the living drafts (which will become available on the week of the 27th).