I had a chat this afternoon with Lee Hunter who is the Drupal Docs lead. Documentation can be a lonely affair, and I think that connecting with other OS projects to share ideas and best practices is great for everyone. I’m hoping to do more of this in the future.
I thought I’d share some of the ideas that we discussed. These are certainly some things I’d like to see implemented/thought about once we get some of the current projects out of the way.
Content Stores
At the last docs chat, the issue of the coding standards was raised. At the minute they exist in two places. Centralised content stores may be the way to go to enable us to reuse content across the documentation. I imagine that we would have the document in one place and then use a shortcode A shortcode is a placeholder used within a WordPress post, page, or widget to insert a form or function generated by a plugin in a specific location on your site. to make it appear somewhere else.
There are issues that will arise out of this. An example is say someone arrives from Google on the CSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site. Coding standards page in the CCH, but actually they need to be in the theme dev handbook. We need some way of displaying where else the content appears so that they can get to where they need to be.
Document Revisions The WordPress revisions system stores a record of each saved draft or published update. The revision system allows you to see what changes were made in each revision by dragging a slider (or using the Next/Previous buttons). The display indicates what has changed in each revision.
Drupal has the Conditional Text Module which they can use to filter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. content according to a specific version. This means that they can support different Drupal versions in the documentation.
I guess this raises discussions about whether we actually want to support previous versions of WordPress within the documentation. After all, we want to keep people updated.
One thought that did come to mind is that Drupal uses tagging to tag specific pieces of text for different versions. In a WordPress context, I can imagine this being useful to display what appeared in different versions. Can we use taxonomies within the actual content as opposed to on the whole page? That might be quite interesting.
Documentation Tracking
Drupal has an issues tracker for Documentation which is something I’d love to see on wp.org. It would be very useful for people to register an issue and for people to be able to see what issues there are an fix them. By keeping track of them in this way be could also organise doc sprints every 6 months to clean up any issues.
They also have a new contributor tasks list which would be useful for us on docs, as well as on core Core is the set of software required to run WordPress. The Core Development Team builds WordPress. .
Another thing that Lee is trying to implement is to allow people to favourite pages. This will let people own a specific page, and receive notifications for changes made to that page. He also mentioned an “Adopt a Page” scheme, in which people own one specific page. I would love to see that. If every WordPress contributor owned just one page we’d have beautiful docs all the time. Once we’re further down the line in terms of building our new docs sections this would be something cool to implement.
Interactive walkthroughs
This is something very exciting which could have a big effect on tutorials and training. A Drupal developer is using the built-in Drupal tour functionality and Selenium to build interactive tutorials. His website is walkthrough.it and he’s running an indiegogo campaign to fund it. The module he’s developing will walk people through complex forms, processes and configs one step at a time. Users are taken through the process, and can make comments on it. In WordPress terms, we could, for example, take someone through the process of setting up their website, or teach them to create content, or manage their multisite Multisite is a WordPress feature which allows users to create a network of sites on a single WordPress installation. Available since WordPress version 3.0, Multisite is a continuation of WPMU or WordPress Multiuser project. WordPress MultiUser project was discontinued and its features were included into WordPress core.https://codex.wordpress.org/Create_A_Network. network. The possibilities are pretty exciting and I wonder if this is something we could think about for WP in the future.
Okay, that’s all of the ideas. I wanted to get them down to gauge interest and see if they are things that we would like to think about in the future. And to see if any of these are projects that people would like to take some initiative on.
Update: I’ve created a dropmark collection with documentation sections we can draw inspiration from. If anyone wants to add to it, set up a dropmark account and let me know your email address for it.
#ideas
