[harrisonjackson]

Did you go to the products page? Not questioning what you said at all just curious how deep you dug (obvs apex should have the info you were missing), but as someone that is pretty familiar with their offering and someone that has hosted api docs and sdk documentation through other sources their copy and marketing is on point for me - and the marketer/founder in me wants to know where the disconnect happened for you.

[choward]

Yes. It was pretty much the first thing I read actually. It makes a little more sense after a re-read. I still have no idea why there are snippets of code at the top telling me how to make a POST request. Anyway, I'm a developer, so when I evaluate something I'm very focused on "how do I use this for real in production and how much pain is it going to cause me?"

So what I usually do first thing is go look for the documentation. When I clicked on "documentation" the first time I expected documentation. It's under the "Products" section at the top and bottom of the page, and that can be interpreted as "product documentation" or "documentation for the product". But as you know, it's the marketing page for a product called "Documentation".

On that page I couldn't really get any more information other than "Easy to Update Within Seconds - Sync your Swagger file, update content in our editor, or merge a suggested edit to make sure docs are always up to date."

I'm not sure what this means. Is this a manual process I have to do or do you have an API call I can hook into my build system?

Is having a Swagger or OpenAPI file a requirement? If not, what's the alternative?

How does the changelog work? Do you read it out of a git repo or manage it on the site?

I have more questions along those lines and I think some screenshots or documentation for actually using the readme documentation product would help a lot.

[gkoberger]

Thanks for the feedback! We can work to make these answers more obvious on the site, but in the meantime:

> I'm not sure what this means. Is this a manual process I have to do or do you have an API call I can hook into my build system?

We do have an API and a CLI tool for automating, or you can sync it in the UI.

> Is having a Swagger or OpenAPI file a requirement? If not, what's the alternative?

Nope, we have a manual editor in the UI for describing your API!

> How does the changelog work?

It's just a blog mostly, but with icons for different types of changes

> Do you read it out of a git repo or manage it on the site?

Everything is on the site, since locking it in git makes it tougher for non technical coworkers to make changes. That being said, you can sync it to git. We have built in page history, versioning, and our own version of pull requests called "suggested edits".

> I have more questions along those lines and I think some screenshots or documentation for actually using the readme documentation product would help a lot.

You can see your docs at https://docs.readme.com

Thanks for the detailed feedback!

[harrisonjackson]

> You can see your docs at https://docs.readme.com

Not _your_ docs, right? lol I think this demonstrates well some of the copy confusion.

[harrisonjackson]

Good to know - maybe some more prominent case studies with links to the real generated end product would be helpful.

The placeholder mockups are a pretty generic side menu / text content area and adding in an Intercom or Trello logo doesn't really clarify what is being mocked.

Definitely some internal vernacular being used in the copy, too. What is a developer hub? Again the mockups dont' clarify much.

100% agree after a second glance the use of "Documentation" as a product is confusing when you consider 99/100 saas/tech companies have a documentation page for _their_ docs. Maybe something like "Hosted Documentation" or "<Your Company's> Documentation" would work. Thanks for the thoughtful response.