Tag Archives: Theme Documentation

Justin Tadlock 6:46 pm on September 15, 2023
Tags: Theme Documentation   

Theme Handbook Overhaul: Phase 3 (Publishing Content)

In April 2023, there was a proposal for overhauling the Theme Handbook, which included an initial outline of what a new handbook might look like. After two public meetings to fine-tune the details of the outline and discuss the project, we moved on to Phase 2. This phase meant writing the new content for the handbook.

Since then, the work has been tracked on GitHub. Now it is time to step into the next phase of this project, but first:

A progress update

The overarching outline for the new handbook is:

  • Welcome to the Theme Handbook
  • Chapter 1: Getting Started
  • Chapter 2: CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. Concepts
  • Chapter 3: Global Settings and Styles (theme.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML.)
  • Chapter 4: Templates
  • Chapter 5: Features
  • Chapter 6: Classic Themes 
  • Chapter 7: Advanced Topics
  • Chapter 8: AccessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility)
  • Chapter 9: Guides
  • Contributing

Thus far, chapters 1-3 (Getting Started, Core Concepts, and Global Settings and Styles) are near completion. That may not seem like much in comparison to the whole, but these are some of the heaviest chapters, at least in terms of new content that must be written.

Much of the content from the Classic Themes and Guides chapters already exists (plus a few docs from the other chapters). They may simply need to be reorganized based on the outline.

Publishing content in Phase 3

In the coming weeks, we should start bringing new content into the handbook, starting with Chapter 3: Global Settings and Styles. Then, as Chapter 4: Templates, Chapter 5: Features, and beyond are written, publish them when ready.

Why skip over the first two chapters?

The first two of the new chapters, Getting Started and Core Concepts, cannot be moved to the handbook until more of the later chapters are published. The primary reason for this is because they are learning pathways to more advanced topics. This means that they have a lot of links to content that hasn’t been written/published yet.

Later chapters are much more self-contained. This means that they can go live without having to wait for all of the new handbook content to be written first.

So both Phase 2 (Creating Content) and Phase 3 (Publishing Content) will now be running simultaneously.

Any help reviewing the current drafts, particularly under Chapter 3: Global Settings and Styles, would be very helpful as we kick-start this next phase. Check out the tracking ticket for the individual tickets.

Phase 4 and beyond

It’s still a little too early to get into the final phase of this project. But once we move most of the new content along, we will discuss how to proceed with the final migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. to the new handbook and any remaining cleanup.

My hope is that we have a new Theme Handbook by the end of 2023. I’m certain there will be continued work, things that we missed, and new features on the horizon. The handbook should be a living document, forever evolving alongside WordPress. This project is as much about setting a foundation for the future as it is revamping the current handbook.

Props to @kafleg for feedback and review on this post.

#theme-documentation

Justin Tadlock 2:34 pm on May 17, 2023
Tags: Theme Documentation   

Theme Handbook Overhaul: Phase 2 (Creating Content)

On April 4, there was a proposal to overhaul the WordPress Theme Handbook that would bring the documentation more up to date, create a new structure, and be more inviting to first-time theme creators.  Since then, the Themes Team has held two meetings where the proposal could be discussed:

  • April 11 team meeting (notes)
  • April 18 handbook meeting

The meetings and open discussion on the proposal post provided an opportunity for everyone to discuss the initial outline (Google Docs link) for the new handbook. Based on feedback over the past month, this outline has largely stayed the same with a handful of adjustments. Thank you to everyone who participated in these discussions and helped shape it into what it is today.

The next steps

Now that we have solidified the overall new handbook outline, it is time to start moving forward with the next steps. The following lays out a plan to tackle actually reshaping the handbook into something new.

This is the part where the project could really use your help! The more people involved with creating content, the more successful this endeavor will be.

Source of truth: 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. https://github.com/ ticket

The Theme Handbook Overhaul Tracking Ticket will serve as the primary location to track and manage the overall progress of this project. 

Essentially, this ticket will list all of the chapters, pages, and sections that need to be created or updated. 

Creating tickets

See something you want to work on? Create a new ticket in the Documentation Issue Tracker (be sure to read the Contributing Guidelines). Once a ticket has been created, we can add it to the primary tracking ticket. 

Creating content

The current plan is to build the new handbook within the existing handbook, moving and adjusting things as necessary. Once most or all of the work is done, the old menu will be replaced with a menu that reflects the updated structure.

As you create content for a specific issue, it will eventually need to be added manually to the Theme Handbook. Because this is an entire overhaul of the handbook, some new pages may need to wait for other pages to be written before they go live. Decisions on how best to handle this may happen on a case-by-case basis.

Reshaping the outline

While we have a pretty solid outline at the moment, things tend to change when you actually get into creating the content of the project. Sometimes things need to be rearranged, added, or changed in some other way. That is not an issue at all, and we can address those situations as they arise.

AccessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility)

The new handbook structure proposes a larger Accessibility chapter. Any contributors who are well-versed in a11yAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility) are definitely needed for this project’s success.

When will the project be complete?

A realistic goal is likely the end of Quarter 3 of 2023. This can be adjusted as needed, but it helps to have a deadline to shoot for. 

With that said, the handbook will never truly be “complete.” Documentation is a living, breathing creature that needs continual care. Even when the initial overhaul is finished, there will always be the need for contributors to continue making it better.

Get involved

If you would like to contribute, just head over to the tracking ticket and find a sub-ticket that needs to be worked on or create a ticket for a handbook page that has yet to be created.

Props to @poena and @kafleg for review.

#theme-documentation

Justin Tadlock 2:46 pm on April 4, 2023
Tags: Theme Documentation   

Theme Handbook Overhaul Proposal

The WordPress Theme Handbook has a lot of great content from numerous contributors over the years. It is filled with wisdom and experience learned from their trial, error, and work. For everyone who has volunteered their time to build this resource: thank you.

The problem with handbooks for ever-changing software is that they need a large re-tuning from time to time. The Theme Handbook has reached that point in its lifespan.

It was created during a time when classic themes were the only method of front-end design for WordPress. Much of its content now exists in a transitory state between classic and modern 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. theming. This has created a scenario where the handbook sometimes reads more like patchwork than if it were built with a single vision. That is often a natural result of adding new documentation over years.

The following is a proposal to give the Theme Handbook the refresh that the theming community deserves.

A New Handbook

Over the past several weeks, I have created an initial outline of what the Theme Handbook could look like. This was based on an analysis of the current content in the handbook and Codex and early feedback from the handbook reps. The outline is also forward-looking with the goal of creating a guide for theme creators in the coming years.

Read the outline document →

I want to stress that this outline is a starting point, a way to get some movement on the proposal. It is not set in stone. The goal is for the theming community to reshape it into something that helps everyone, including both first-time creators and seasoned developers. We may end up with something entirely different from the current outline document.

This proposal is to overhaul the entire Theme Handbook. That means that no idea is  too “crazy” during this stage. So, dream big and share your vision for what the handbook should be in the comments below.

With that in mind, it is important to set some dates and not leave this so open-ended that nothing moves forward. Therefore, the feedback period for the outline ends on April 28, 2023. That provides nearly a four-week period for us to work alongside each other to create an outline for a new theme handbook.

The outline proposal will be on the agenda for discussion during the Themes Team meeting on April 11, 2023 at 15:00 UTC. 

There will also be a dedicated meeting on April 18, 2023 at 13:00 UTC via the #themereview channel on SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/.. Everyone is welcome to join and discuss this proposal in detail.

Questions and (Some) Answers

How do I participate in the outlining process?

There are currently four ways to get involved:

  • Leave a comment on this post with your feedback and ideas.
  • Discuss during the Themes Team meeting on April 11, 2023 at 15:00 UTC via the #themereview Slack channel.
  • Join us for the outline proposal meeting on April 18, 2023 at 13:00 UTC via the #themereview Slack channel.
  • Make suggestions directly in the Google Doc for the outline.

What are the next steps after the outlining process?

In the upcoming meeting, we can start to define the next steps on following through with this proposal. This should include, at least, a new ticket on the Documentation Issue Tracker with an overarching plan.

Who will create the content for the handbook?

We all will. The Theme Handbook is and has always been a community project. The more people involved, the better the resource is for us all.

What will happen to existing content?

There is no reason to remove the content the handbook already has. There is a lot of great material there that we should carry forward. Some of it might need to be updated or reorganized, but that can be tackled during the next step. The goal at the moment is to primarily improve the overall outline and flow of the handbook.

Why are Classic Themes in a single chapter?

The goal of the outline was to explore the handbook from a modern perspective and one that will best serve creators in the coming years. It makes sense that the focus of the handbook should be on block theming, especially now that the Site Editor is out of 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.. Block themes are the present and future of WordPress. 

The outline also makes room for all of the existing content to be migrated to appropriate sections, much of it under a dedicated Classic Themes chapter. Classic theming isn’t disappearing, but the current handbook often makes for confusing reading jumping back and forth between classic and block theme examples.

Like the rest of the outline, this is 100% open for discussion.

What happens to permalinks with the current handbook?

I don’t have an answer for that yet. It would certainly be a part of whatever the final proposal becomes. Some ideas that have been thrown around so far have been a redirect solution or to create a “v2” of the handbook with the old version being archived in much the same way as the Codex still exists. I also don’t think that is a major concern until the outline is finished. It may be easier to simply incorporate new sections/pages into the existing handbook. Whatever the case, it’s best not to let this discussion deter us from creating a new vision.

In other words: let’s cross that bridge when we come to it.

Will there be a new design?

The handbook designs are outside the scope of the Themes and Documentation teams. The Design team has been routinely sharing what many of the pages of an upcoming redesign will look like via the #design-share tag. There is a definite need for a full overhaul of the design that works well for documentation-style pages. Anyone interested in that aspect should visit the Get Involved page of the Design Team handbook.

Props to @poena, @kafleg, and @juanmaguitar for their feedback on this proposal.

#theme-documentation

Michael Burridge 9:29 am on December 3, 2021
Tags: , Theme Documentation   

New directory names for block-based (FSE) themes

TL;DR:
As of the currently available WordPress 5.9 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. 1 release the directory names in 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.-based (FSEFSE Short for Full Site Editing, a project for the Gutenberg plugin and the editor where a full page layout is created using only blocks.) themes are changing. The name for the directory containing template files will be templates, and the name for the directory containing template part files will be parts.

WordPress 5.9 will be released on 25 January 2022 (see the current release schedule here) and marks the arrival of block-based themes, also known as full-site editing (FSE).

Developers who have already experimented with creating block-based themes during the run-up to the release of 5.9 should note that the directory names for templates and template parts are being changed.

Previously the names for the directories containing template files and template part files were:

  • block-templates
  • block-template-parts

With the release of 5.9 these will instead be:

  • templates
  • parts

This change is detailed in PR #36647. The documentation in the Block Theme Overview and Create a block theme pages has been updated to reflect this.

The rationale behind this change is that it creates a cleaner and clearer directory naming paradigm that will simplify the addition of further directories in the future, such as styles and patterns , should they be needed.

For more insight into the rationale underlying this change please see issues #34550 and #36548.

This change is backwards compatible and the old names will still continue to work, but note that the old and new directory names are mutually exclusive and cannot be combined. You cannot call one directory block-templates and the other parts, for example.

This change is already implemented in the currently available Beta 1 release of WordPress 5.9.

#block-based-themes, #theme-documentation
Emil Uzelac 5:38 am on January 7, 2013
Tags: Theme Documentation   

Changelog: Recommendation or Requirement?

Theme Documentation:

In lieu of a readme.txt file, Themes are recommended to include a changelog, indicating version-to-version Theme changes.

In past months we noticed that Theme Authors either do not have the changelog or the changelog is very poor.

Here are some examples:

Changelog

  • Version 1.1 – Improvements
  • Version 1.1 – Minor Menu Changes
  • Version 1.1 – Font Size Change

Which does not really say anything at all.

Or the changelog that was not updated in months.

Luckily for us we have tracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/., but it would be easier for us and for users to know what is going on when author releases a Theme.

Please share your thoughts.

Thanks!

#theme-documentation