A week with us: why we care about documentation and team update
At Yoast, we believe good documentation is important for any software project, and it’s essential for open source. Documentation is building a legacy. So, whatever we do, people will be able to pick it up and continue. If you are starting out or are upskilling, you are probably looking for good documentation yourself. And even if you are an experienced developer, I am sure you appreciate clear explanations and guidance from time to time.
Raise your hand if you checked the code you wrote years ago and you are ashamed of it. I certainly did! So much that in some cases I asked people to remove my name from the footer of websites I built.
Some developers believe that documentation writes itself because the code they produce is so good that they don’t need to add any explanation. While this is definitely a good goal, such a thing doesn’t really exist. Even very well-written code always needs context, and the context might change quite quickly in tech!
We are committed to improving documentation for WordPress
The Yoast WordPress core team is particularly passionate about this. Documenting a commercial project is definitely easier. You can always hire someone to write it. In this case, please do it as you go and not as an afterthought.
In open-source, things are trickier. Different people work on different parts of the project. Their commitment and availability can vary, and not everyone has the skill for writing documentation. Furthermore, contributors who are no longer active might have written the documentation years ago, and no one has updated it since. Sometimes, sadly, no one wrote the documentation at all. And finally, contributors might have added new sections without looking at the whole picture holistically. As a result, from a single page about a specific topic, you can find yourself, years later, with a behemoth to take care of.
In August 2020, Justin joined our team with a specific focus on documentation. With the help of Paal Joachim Romdahl and the Docs team, he is working on the Gutenberg developer documentation. Huge effort!
Google Season of Docs
Last year, WordPress took part in the Google Season of Docs, an initiative that
provides support for open source projects to improve their documentation and gives professional technical writers an opportunity to gain experience in open source.
It definitely helped, and I am personally happy to see it come back for another year. We have been chatting with Josepha Haden, WordPress.org Executive Assistant, and Chloé Bringmann, her chief of staff who was the WordPress Administrator for the last season of docs, to evaluate if this year we can help with this task.
Our founder, Joost de Valk said it best:
In many ways, we like to be “the grease” for some parts of WordPress. We like fixing the things that need to work but that don’t get enough love
Hopefully, we will be able to continue to give enough tender love and care to documentation. In my opinion, that’s the highest form of generosity when it comes to open-source.
This week I continued working on a proof of concept to allow the use of hybrid themes in Full Site Editing (FSE for short) in Gutenberg. Allowing the use of hybrid themes would go a long way to ease the adoption of FSE in the future and would be a significant step in a viable solution for theme-developers. Developers would be able to start taking advantage of parts of FSE without the need to convert their whole theme to a block-based structure all at once. It will be possible to do it incrementally!
There are a lot of great ideas in the Gutenberg GitHub repository, dozens of developers who want to contribute with code and submit pull-requests. So one of the major tasks this week was helping others get their ideas implemented by reviewing a lot of these pull-requests and finding solutions to issues. Anyone can help, so if you have some time and are looking for ways to contribute, reviewing code is a great way to learn more about Gutenberg and at the same time help others improve their skills :)
On the 23 of February, Josepha Haden and Matt Mullenweg invited Ari and me to a meeting, together with representatives from the WordPress.org meta team and the themes team. We discussed the future of the official theme directory and potential improvements to it. We also talked about how we can measure the theme directory’s success for the long term.
Right now, developers who would like to include a theme in the theme directory need to follow many complex rules, and the waiting time to add a theme can be over one month. Hopefully, we can soon find a solution for this and make it easier to submit themes. If you would like to read the meeting notes, you can find them on the themes team’s blog.
Speaking of documentation, on Thursday, the docs team did a quick review of an outline of the end-user documentation for full site editing. However, everyone agreed that it is still too early to start writing the documentation.
Last week I was on holiday. It took me over twenty years of work to understand the importance of work-life balance and recognize the need for time off as an integral part of being an effective employee.
This week, I’m working on the last steps of the Gutenberg developer documentation restructuring project.
Since it’s a rather massive change that will be integrated, it’s important to be meticulous and make sure that everything is done correctly. Some jobs need to be run on the website just before and after the integration of the changes, I’m coordinating all this with the Meta team.
Moreover, I am planning the next contribution projects that I will work on starting in the second quarter of the year. I already have a couple of ideas, and it looks very exciting.
Last week, my main focus was to continue reviewing tickets for the upcoming major release of WordPress, as part of my duties as the Core Tech lead. I made twenty three commits to WordPress Core, ran mission control for WordPress 5.7 Release Candidate, and triaged new tickets incoming into Trac (the bug tracking system that WordPress uses).
Now that WordPress 5.7 has reached the release candidate stage, only regressions are addressed at this point.
I’ve also started reviewing enhancements and bug fixes for WordPress 5.8.
As WordPress 5.7 nears release, I’m wrapping up documentation and moving my focus back over to other tasks.
Over to you! Questions?
Do you have any questions for our team? Please leave them in the comment. We would love to use this space for dialogue and not only to broadcast. Ask us anything!