What Changes Would You Make to the Docs Site?

[katie.richards]

The Pantheon Documentation team’s goal is to provide high quality, accessible, user-friendly documentation for our customers. With the thought of continuous improvement in mind, the docs team is making improvements to the docs site this year.

Do you have a favorite documentation site? What do you like about it (easy to search, structure, links, style)?

If you could change one thing about our documentation, what would it be?

Drop your thoughts in a reply and feel free to include URLs, screen shots, or other details that will help us level up our documentation!

[bsharpe]

I’d like to see a timeline with last updated, created etc.
Also some indication about why the documentation is there.

Eg. I search for information on best practice dealing with “API keys” on Pantheon.
I get this https://pantheon.io/docs/guides/lockr

I see that it was written by the person who founded the service. But I don’t know when it was written.
More importantly I don’t know how much this is supported by Pantheon, a best practice, and what other alternatives are suggested. I get that Pantheon might try to not be opinionated on it, but it would be good to have some more context why the doc for this integration is here.

I start from an idea that all documentation is a Pantheon initiative, but I get the sense sometimes that a particular solution is maybe there b/c someone was motivated to do it outside of Pantheon.

(otherwise I do really enjoy the docs here

[carolyn]

First, welcome to the Pantheon Community discussion board! Our docs are better because of the contributions of many, including those in our community. Thank you for taking the time to offer suggestions.

Last updated: +1 great suggestion. “Freshness dates” give readers important cues that help build trust in the content.

Last year, we began adding visible “Last Reviewed” dates to docs, but not all have them yet (including this particular one). We are working to meet our goal of adding them to all our content, and I appreciate your support for that goal!

Why does this doc exist?: Our docs exist to help you be successful using Pantheon’s products and services.

Context: I really appreciate your note here on the importance of context in docs.

Pantheon’s platform is indeed opinionated, and our docs reflect that with best practices, based on the expertise of both our internal subject matter experts and also community contributors who build often-used and recommended tools.

If something is unsupported or experimental, the docs will note that.

It sounds like for this doc, it would be helpful to include additional context about how this tool fits into our best practices recommendations for API key management. Context is key; with that in mind, we will review this one to ensure these instructions fit into the larger context of ways to manage API keys with Pantheon sites.

I don’t know if you have Github credentials, but based on your feedback we’ve created an issue (DOCS 6235) you can track for this particular doc. If you’re available, I’d love to include you as a reviewer for the update to ensure we’re hitting the mark. Thanks again!

[bsharpe]

Great. Thanks for the thoughtful response.

I really appreciated this doc: https://pantheon.io/docs/email

As an underfunded, non-profit, we try to choose solutions we know will be prioritized, supported and documented within the ecosystem (Pantheon) we are in. This page gave a good overview of what ppl are using here, pathways to making them successful and then seemed to highlight Sendgrid as a well supported method with good ecosystem documentation.

In general when I see documentation about a 3rd party service written by a key owner of that service, I value it as expert knowledge, but I do get flags about the maintenance of that documentation and it’s relationship to the ecosystem. So the context/connectedness/freshness helps with that.

Also I should mention that this in no way is an opinion about Lockr. I think it’s a great service. Just was a clear example for the discussion as I had been looking to recommend a consistent practice for my team and was looking to compare.