Much of the WP REST API v2 documentation is automatically generated from demo.wp-api.org/wp-json/?context=help. A Ruby script dumps the JSON into _data, and Jekyll generates pages like this:
It would be cool if someone wrote a WordPress theme (or plugin) to automatically generate a documentation site from a WP REST API index — and the only configuration parameter was the URL to the endpoint.
stephenharris/wp-readme-to-markdown. If you maintain any WordPress plugins on Github, this is pretty freaking awesome.
danielbachhuber/wp-dev-docs. As I perform code reviews for Hand Built, I’m building out a repo of reference documentation to refer to that you can use too.
Hitting up Write The Docs for the next two days. Considering it’s only four blocks away, it already has serious points towards its awesomeness.
Conference goal: obtain necessary ideas to get the WordPress Plugin Developer handbook back on track.
Document Feedback is a new WordPress plugin to close the loop between documentation writers and readers.
By default, it appends a simple prompt to the bottom of every Page:
If a reader responds to the prompt, they’re given a follow-up question to clarify their response. Readers must be logged in for the prompt to show up.
Comments are emailed to the post author and summarized in a post meta box:
Many thanks to Mario Peshev for his random hacks of kindness. I started this plugin a year ago and left it half-finished on Github. Then Mario comes along, submits a couple very substantial pull requests, and kicks me in the pants to release it.
Join the fun on Github or use the WordPress.org forums for questions / bug reports. This plugin is already live for the WordPress.com VIP documentation portal, and is available for use by VIP and Enterprise clients.
Prompted by this thread, it would be neat if the plugin directory supported translations for documentation and FAQs. This could be support for secondary copies of the plugin readme with the locale as a part of the filename (e.g. readme.en_GB.txt).
Writing beginner level tutorials. A number of useful tips. My favorite: “use words and phrases that your reader can Google to find more information.” For producers of documentation, I think the biggest challenge is putting yourself in the mindset of the reader. The second biggest challenge is closing the feedback loop between the person who has the knowledge and the person who wants the knowledge.
Idea: make learning best practices, coding standards, etc. more engaging by converting standard documentation into interactive quizzes and games. This would also provide feedback to the instructor on which topics were understood and which need reinforcement. We could use this as a part of the onramp process for new Code Poets to reduce the number of basic issues (like validation vs. sanitization vs. escaping) we’re currently communicating over and over.
Idea: Prioritize frequently asked questions on an external facing documentation site based on how often the questions get asked in support tickets. Show the number of times a given question was asked this month as a way of indicating to the customer that the answer probably already solves their question.
What follows is a laundry list of all of the things I planned out but never got around to doing at the J-School. Some are crazily creative while others are to be expected. I’m writing them out because I want to retain a record of them for the future (and now they mostly live in a Basecamp account I’ll no longer have access to).
At the time of this writing, the J-School has two WordPress multisite instances. One, at journalism.cuny.edu, subdomains of the primary domain, and various custom domains, offers managed websites for students, faculty, staff, and alumni. The other, CUNY Campus Wire, is managed hosting for CUNY student publications.
- Post by email – Create new posts, let them be blog posts, galleries, links, etc., via email. Also, offer the ability to respond to a comment thread by email.
- Search across all sites in the network – Have a dedicated URL like http://search.journalism.cuny.edu/ to run a query across all sites in the network, and offer faceted filtering to limit result types to specific content, authors, topics, etc.
- Dynamic homepage for logged-in users – For J-School community members, the homepage becomes their dashboard for the school, including assignment information, upcoming events, discussion notifications, etc.
- Ingest users’ social media content – Pull in and make available tweets, Flickr photos, video, and other social media from WordPress users. Offer BuddyPress profile fields for users to enter their identity information or, better yet, allow them to authenticate against the website using their third-party accounts. Use this data to build features like a realtime map of where community members are based on geo-tagged tweets or Foursquare checkins.
- Community tagging – Any user of the network can suggest tags for a content object, including people, topics, and places.
- Contextual documentation based on Tech website content – In the WordPress admin, replace the generic help tab documentation with custom documentation from the Tech website. Optionally allow users to create a new support ticket from the WordPress admin.
- Soundslides WordPress plugin – Make it easier for students to publish Soundslides projects by allowing them to upload publish_to_web projects through the admin and embed with a shortcode.
- Take a screenshot of each website homepage once a month – Offer a visual archive of how sites are evolving over time.
- Network usage stats plugin – Track usage across the network. Data points like:
- Total number of sites and users
- Posts published, media content uploaded
- Links used per post, by site and globally
- Total embedded rich media
- Users active within the last week
- Number of sites using a given plugin or theme; see which is using what from the network admin
- Distribution of custom CSS modifications by site, possibly correlated to theme
- Most popular CSS property for custom CSS modifications
For the last few months, we’ve spent a significant amount of time revamping our tech website. The focus now is producing documentation on every subject the team deals with, but eventually the vision is to have the website be the primary way for clients to access resources and interface with the tech team.
- “Was this helpful?” – At the end of every piece of documentation, allow the reader to indicate whether it was helpful or not. If they mark “No”, display a small box for them to submit a comment. Optionally, enable the document author to define what the question is.
- Content notifications – Alert authors by email if their documentation hasn’t been updated in a while.
- Public plugin and theme directories – Make it much easier for users to see which plugins and themes they have available to use by building a directory for each into the tech website. Both single views would have details about the object, related documentation and blog posts, usage stats, and links to examples.
- Support ticketing – Move support ticketing from the ever-awful Web Help Desk into WordPress. Users could create new tickets directed towards staff, or towards other users in the system (when creating a ticket, users would be suggested based on relevance). Tickets can be private or public, and sortable by tags so we can pull out metrics and see history easily (i.e. 163 students didn’t know how to log into WP in the last two months). A ticketing system should empower you to be proactive about support.
- Issues as a custom post type – Create “issues” as a custom post type (network downtime, failure, classroom equipment outages) and build a view for open, pending, and past issues.
- Equipment availability – See what equipment is available for checkout when.
- Live refresh on search results – A la the 37signals documentation site and Google Instant.
CUNY J-Camp website
CUNY J-Camp is the brand for the J-School’s continuing education workshops. We launched a redesign in June 2011 that is well-positioned for additional improvement.
- Support WordPress galleries – Allow for the instructor to upload images after the event and, optionally, for participants to upload their content as well. Add theme support for galleries, with a nice interface for going through all of them
- Calendar view – By default, events are presented on the homepage in a nice grid view. A secondary view could be a month-by-month calendar so visitors can see what workshops were held in the past and what’s coming up in the future.
- Registration through WordPress – J-Camp workshop registration is handled through Eventbrite. This is functional, but we could do so much more, like track user participation over time, if it was handled within the theme.
Digital media management odds and ends
Officially, my title at the J-School was “Digital Media Manager.” I always introduced myself as “the internet guy at the J-School”, and the job included everything from server admin to designing print ads to managing digital media…
- Web interface for accessing Aperture – Build on the Aperture’s database of media metadata, and make those assets available through a web interface so stakeholders can view and download content without having Aperture installed on their local machine. The syncing offered in Aperture 3 really isn’t functional.
- Digital signage WordPress theme – Design and build a WordPress theme to power the digital signage in the newsroom, on the first floor, and other places to be determined. Inspiration is Macaulay College’s implementation. Ours should rotate through events, photos, student work, “Did you know?” facts, news items, and J-School branding. Could also incorporate other network content like posts and updates.