Pantheon Community

WordPress Documentation: What are we missing?

Hi folks! The Pantheon documentation team wants to hear from you about WordPress content. Specifically:

  • What are we missing? What new content do you want to see added to our Documentation to help you and the WordPress community succeed on Pantheon?

  • More generally, what topics aren’t well covered by the WordPress community as a whole, where we could help everyone?

  • What’s wrong? Do we have old, stale, or just plain wrong information? Bad docs are worse than missing docs, so if we’re saying the wrong thing we want to know about it!

  • What are we doing right? If there’s a doc or guide that you think exemplifies good WordPress documentation on Pantheon, please let us know! We’ll look at what works best from those docs as something to strive for in new content.

As always, the Pantheon Docs team truly appreciates your input and help!

I know that I’ve had to fill in the gaps in documentation for business owners I’ve built sites for by rewriting or simplifying a bunch of the documentation. I know the docs are mainly there for practitioners like us who know what a command line is for and who intuitively understand many of the vocabulary words. But it would be of great worth to business owners who seek a level of self-sufficiency if they could access a site with a version of the docs that is a little more basic, or at least starts where they are vs. where we are in their understanding.

1 Like

Thanks @webidextrous! In general, I try to write documentation for all users to consume, including or linking to pre requisite knowledge where needed. What sort of topics do you think need to be focused on for business owners?

As an aside, even developers need documentation that doesn’t assume knowledge. When I started looking into the WordPress API, I found yet another reference manual that assume you’re already an API wizard, only offering the details specific to this one endpoint.

So I started writing a new doc on The WordPress API. That link goes to the staging environment for my word in progress.

WordPress devs, what do you wish you knew when you first started learning about APIs, or the WordPress API in example? What example calls best reflect common uses?

You can also view the source content on GitHub, or make pull requests to that branch if you want to contribute content to this idea.

All feedback on this topic (WordPress API) and the larger question (WordPress content gaps) are welcome and encouraged!

Thanks, Alex, for all you’re doing. Documentation, as we all know, is never fully “done”. I think, just in general, for the types of super non-technical clients I’ve been working with, videos with a super-friendly and engaging voiceover that really emphasize the “why” of what is going on in a set of instructions really help. A lot of times, they just don’t “get” why they’re doing a particular thing or typing a particular command. It makes the videos a bit longer, but the in-depth explanations go a long way towards building understanding of what, to them, is a completely foreign language.

Personas to write for in my corner of the world include stay-at-home-moms selling antiques, psychiatrists/psychologists with ADHD helping others with their same condition, travel agents whose second language is English and have no technical skills, leadership speakers, life coaches, and real estate agents. None of these personas have large enough businesses to have an IT expert on staff. They’re either doing it all themselves or spending more than they can afford on agencies and hoping that their spend will pay off in the future.

Thank you for writing the WordPress API doc. I’m actually just starting on a project where that will be super helpful. I know what the API is, what it’s for, and generally how it’s used. But I crave useful, real-world, copy/paste/change-able code snippets that will help me figure out how to connect to them and consume the output in typical scenarios and use cases. You’re on the right track and I am looking forward to using it when it’s done.

1 Like

@alex So, here’s a real-world example. I’m following the API doc you wrote and, knowing that it’s not completed yet, I’m hoping you can point me in the right direction.

I’m trying to output Yotpo review stars and other metadata onto WooCommerce product pages. I need to consume the Yotpo API and basically do on the server side, pre-render, what their standard JS code snippet does in the header.php as the page renders. The idea is to reduce the processing/request overhead that their JS snippet imposes during render and just go direct via REST and output static HTML for the metadata instead.

I’ve never done this before, so I don’t even know where to begin. Google isn’t helpful because I don’t know exactly what to search for as to a starting point. I’ve watched a Lynda tutorial, but it lacked detail. I’ve run the curl commands you noted in the docs, but I get stuck here with a 401 error when trying to get a utoken. I have the API Key and Secret, but their documentation isn’t specific enough to fill in what else I’m missing. Every time I’ve asked them for help they tell me that’s out of the support scope and to hire a developer, which isn’t an option for me right now. I’m assigned to do this so I have to get this done. Somehow.

Is there a good tutorial out there? Some PHP code or JS code that’s good for this? What else do I need? Where do I put it? How do I integrate it into a WordPress plugin or functions.php? So many questions, so few plain English answers.