Community Summit Discussion Notes: Ad hoc session on iterating on the Field Guide

This was a follow-up session over lunch building on the backwards compatibility session.

Date: August 23, 2023

Attendees: @ellatrix @mcsf @ndiego @clorith @bernhard-reiter @timothyblynjacobs @jorbin @priethor @annezazu @richtabor @gziolo. Everyone consented to being listed here since it was an ad hoc session.


History of Field Guide

Around 3.2 – 3.3, there was a field guide around backwards compatibility from Nacin. Around RC1, having an email to pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the Plugin Directory or can be cost-based plugin from a third-party developers came up and the email that was created was too much for an email, resulting in a post published on Make. This evolved to become the Field Guide process after being well received by the community. It has since grown in length every single version. When looking at a visual comparison, it is now 6 times as long in length just to look through, making it harder to scan.

Questions to frame the conversation

The following questions were used to guide and frame the conversation:

  • How can the content of the Field Guide by reformatted to improve developer messaging?
  • Is the Make blog the right channel for this resource for folks to engage with?

Developer blog discussion

Developer blog is relatively new and right now anyone in the community can contribute to it. It’s a small group of folks currently along with a monthly “what’s new” roll up that could be expanded and built upon. The original idea of the developer blog was to cut through the noise and provide valuable resources to extenders. This then reserves the Make Blog for folks who make WordPress. There’s more of a process with the dev blog currently that might make it trickier to stick to.

Information spread out

When googling for features or updates, there’s a confusing experience where what comes up could be something from 4-5 years ago rather than linking to documentation. This is due to posts being shared on Make CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. that then start getting linked to and shared, causing the weighting of that post to go up and the first hit on Google is a dev note rather than documentation. We might need to return to dev notes after docs are updated to link to documentation as a way to redirect folks to the latest.

Specific to dev notes, there’s also an issue of dev note being a form of documentation and acting in place of documentation rather than “here’s what’s breaking”. Right now, dev notes are both acting as docs and breaking changes basically. 

If you go a step further to look at blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. editor handbook docs, it includes a mishmash of content. Work is underway right now to ensure learning/tutorials get into Learn WP and documentation remains in docs. Docs in general though are scattered in official blog posts, unofficial blog posts, dev notes, dev handbook, user facing docs, etc. It’s not necessarily bad that it’s in so many places but are things going to the right places or are things getting missed? This comes down to even basic formatting changes like labeling things as “breaking changes” or having a dedicated section for breaking/high impact changes. Right now, it’s broken down by component rather than priority for the Field Guide.

Content reformatting

When thinking about the format and approach of the Field Guide the following questions were thrown around when thinking about the persona of a person using the Field Guide: Are there big UIUI UI is an acronym for User Interface - the layout of the page the user interacts with. Think ‘how are they doing that’ and less about what they are doing. changes to inform customers about or update plugin around? Are there things that might break and what do I need to do about it? What are the big things in the release? Where can I get more information? This led to an idea of two Field Guides with different approaches:

  • A hyper focused version with more curated info. 
  • A longer, more robust version. 

Right now, separating out a curated source requires a level of expertise to determine what’s most relevant that isn’t widespread in the project.

Pain points in getting early feedback from extenders

We talked about the general process before a release and getting folks to test, give feedback, etc as part of the broader process of sharing dev notes. Before a release, there are alpha/betaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. forums where you can get some feedback but it doesn’t often go anywhere. Developers are more likely to use TracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub. and GithubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. so we can point them more in that direction to get feedback. In general, getting devs to beta test or RCRelease Candidate A beta version of software with the potential to be a final product, which is ready to release unless significant bugs emerge. test is very hard. 

Iframing the editor example

To ground the conversation in a specific example, we talked in depth about work around iframing. For some plugins, they didn’t reactReact React is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces. because they felt there would be a fix in the future for iframing rather than taking action and reporting something on. We can’t make changes if we don’t know about the feedback though!

The WordPress Developer Blog would be a good way to surface issues like iframing and go in depth about ways to overcome different pathways for adopting. If this effort is backed up with documentation, it could help cover the big, breaking topics nicely.

We went on a bit of tangent around how we could use Site Health with lack of iframing to help encourage folks adopting. In general, for larger changes like iframeiframe iFrame is an acronym for an inline frame. An iFrame is used inside a webpage to load another HTML document and render it. This HTML document may also contain JavaScript and/or CSS which is loaded at the time when iframe tag is parsed by the user’s browser., we need to think of communication plans as part of the effort. For iframe, every situation is quite different so it’s tricky to get right. Developer Relations should be able to help here. DevRel is tricky within open sourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL. since it’s typically going to have to be sponsored by a company, which then brings in bias and questions around motive for amplifying certain changes. At the same time, we need folks who are doing the outreach and engaging.

Motivation to adapt to changes

Part of what has to be considered is what the sell is to update things, especially if there aren’t clear benefits. This can be metered against having things in Site Health that informs users that plugins might not be doing their work to keep up to date. Having warnings could help encourage better practices and have folks address problems. The more we can make it visible, the more it will reinforce updating.

Deprecation strategies

The topic of deprecations came up: When we deprecate something, when does it get removed? We should look at timeframes for figuring out how best to handle and communicate. This can be tough for implementors and has been in the past when things are changing so fast. This came up when the GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. plugin first came out and work was done to encourage folks to build with it while things were also changing so quickly. This led to some mistrust and frustration. We still have things from PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. from 0.7.1 that we deprecated but didn’t remove so this is a larger problem. Some inelegant solutions were thrown around before focusing back on the main topic of communicating and the Field Guide.

Documentation and Dev notes

Dev notes in general are rough to find and some of this could be improved with The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. website redesign. Dev notes should feed documentation that gets regularly updated and maintained. We talked about application passwords work where the info is only in a dev note rather than in docs and how that’s a problem. 

A more limited set of folks can write documentation places but it’s fairly open to write on the Make Network. For developers, it becomes easier to just do dev notes rather than helping with docs. The documentation team should be able to handle these doc updates from dev notes though. The docs team has a repo where you can create a ticket and they can handle changes, except for the block editor handbook which is handled on GitHub. In theory, a step could be just to create a GitHub issue of the dev note changes and have those docs updated.

Timeline of dev notes

We talked about how dev notes require submissions by a certain timeline but, in truth, things get done throughout the release sometimes as late as RC4. At the same time, dev notes are useful for comments/feedback and iterating on the messaging. If the updates were moved straight to docs, you would miss that engagement and opportunity to do better.

Next steps: 

  • Propose that the responsibility of docs lead could be to help ensure dev notes get into dev docs. 
  • Update dev notes after when docs are updated to help with SEO problems. 
  • Go through dev note tracking issue (example) in GitHub for priority/sense of breaking changes and explore the idea of having a dedicated “breaking changes” section in the Field Guide.
  • Explore the idea of two Field Guides: A hyper focused version with more curated info & a longer, more robust version. 
  • Do a theme author email similar to plugin author to communicate breaking changes. 
  • Re-think dev notes and see what can be evolved in the handbook since the first introduction. 
  • Create a pattern for dev notes to create more consistency and ease of writing. 
  • Ship dedicated developer blog post for breaking changes that get deeper into the changes. 

#summit, #summit-2023