EDDYMENS

Writing

Published 3 weeks ago

Readme.io Documentation Platform: A Review

Table of contents

Introduction

Readme.io [↗] is a platform for hosting developer documentation, including guides and OpenAPI specifications [↗]. It’s a hosted service, so you don’t need to set it up on your own servers.

In this article, we will explore the various features and functionalities offered by Readme.io, starting with the pricing tiers. This is a personal and open review based on my experience.

Pricing Overview

As of 2024, Readme.io offers four pricing tiers:

Free Tier:The free tier allows you to host your OpenAPI specs, but you can’t use a custom domain, and your documentation will display the Readme.io branding.

Startup Tier:The Startup tier lets you host both markdown guides and OpenAPI specs. You can also use your own domain name and remove the Readme.io branding. The Startup tier costs $99 per month.

Business Tier:The Business tier allows you to create static pages with some limitations. For example, while you can style your pages, the styles are applied globally across all pages, so you will need to scope them yourself to prevent unintended effects on other pages, including those styled by the platform. This tier costs $399 per month.

Enterprise Tier:The Enterprise tier gives you the ability to control who sees which documents, allowing for private documentation protected by standard or SSO authentication. You can also stage your docs before publishing. This tier is ideal for large businesses with multiple products and extensive documentation. The cost for this tier is $3000 per month.

You can find the full feature list and pricing breakdown on the pricing page [↗].

Readme.io adheres to several compliance standards, including GDPR [↗] and SOC2 [↗], which are important for companies that require vendors and subprocessors to be compliant.

Most of the data collected by Readme.io includes emails for authentication and tracking data for analytics. It’s also worth noting that most of Readme.io’s servers are located in North America.

Readme.io provides all of their compliance reports on a single page [↗], and you can contact their compliance team via email if needed.

Note: Some of the information mentioned here may change in the future, so it’s best to consult their compliance page [↗] for the latest updates.

Analytics

Readme.io Analytics page [→]

Out of the box, you get some analytics with all plans. The analytics feature tracks page views, identifies new and returning users, and highlights the top pages. You can also see what users are searching for on your pages and track API requests if you enable the interactive API feature.

Additionally, you can integrate Google Analytics by inserting your integration ID.

User Management and Authentication

You can grant admin access to other team members, giving them full access to the Readme.io dashboard. You can also allow readers to create an account, linking their profile to your analytics.

By default, logging in is done via a simple email/password combination, but higher tiers allow you to integrate your company’s SSO [↗] setup.

Authoring and Collaboration

Readme.io Built-in editor [→]

You have two main options for authoring your documentation: using the built-in editor or the Docs-As-Code [↗] approach.

The built-in editor is mainly for general content (guides). It’s basic but gets the job done. For API specs, you can manually upload them to the platform. The editor also has a history log, so you can revert changes if needed.

The Docs-As-Code approach uses a toolbelt [↗]/CLI provided by Readme.io, allowing you to upload docs from your system to the platform. This means you can use your preferred authoring tools and only use Readme as a publishing platform.

The downside of using hosted documentation platforms with a Docs-As-Code process is that you typically can’t preview your docs until they’re published.

Markdown Support

Readme.io Stacked markdown support [→]

The markdown support is standard and includes most features you would expect. There are some extras [↗], like converting consecutive code blocks into tabs, which you can label.

In your Markdown documents, you will need to include some special front-matter entries [↗] to help the platform know where to place your guides, what to call them, and what SEO metadata to use.

OpenAPI Support

Readme.io Sample API docs [→]

Readme.io supports both OAS2 and OAS3, providing sample code in several languages that users can copy and run. Users can also fill in fields generated from the spec to create the request payload needed for the code sample.

If you provide users with a sandbox environment, they can test their code directly within the docs.

Customization and Theming

Depending on your plan, you can make basic layout and color changes. If you’re willing to dig deeper, you can customize with CSS, though this isn’t officially supported as there’s no documentation on how to hook into the platform’s elements.

Handling Images

When creating documentation through the editor, you can upload images as part of the process. However, if you’re using the Docs-As-Code approach, the CLI doesn’t support image uploads. The team recommends using a third-party service like S3 [↗] for image hosting.

Currently, I allow all writers to access the editor, where we have a hidden page for uploading images. They can then grab the URL and add it to their markdown documents. This process is less than ideal, especially for paid plans.

Readme.io Redirects page [→]

With the Business and Enterprise plans, you can set page redirects, which is useful when moving documents around.

Other Features

Depending on your plan, you may have access to these features:

  • Staging: Preview your docs before publishing.
  • Versioning: Maintain multiple versions of your docs that align with product versions.
  • Recipes: A unique Readme.io feature [↗] that allows you to layer walkthrough text over code samples.
  • Reusable Content: [↗] Useful for reusing content across multiple documents and making changes in one place.

SEO Considerations

If you’re focused on SEO, you might find the platform’s features somewhat limiting. However, Readme.io has made efforts to comply with basic SEO requirements. For example, although the platform is an SPA [→], crawlers receive a prerendered page with your content, which helps with SEO. Load speeds are also good.

Users on the free tier might benefit from the Readme.io URL structure i.e: . A quick Google search [↗] for Readme.io shows many businesses on the free tier. This might not be ideal for Readme.io as a company.

Integrations

Readme.io offers several integrations out of the box, and depending on your tier, you might be able to request additional integrations.

Out-of-the-box integrations include:

  • Google Analytics
  • Google & Bing search verification
  • Intercom
  • Slack
  • Zendesk
  • Segment
  • Localize
  • Heap
  • ReCapture
  • TypeKit

Localization

You can integrate with the third-party service Localize [↗] for your localization needs.

Conclusion

Overall, Readme.io has been a solid platform for hosting documentation. If you prefer a hands-off approach to platform management, Readme.io is a good choice, though image uploads are a significant drawback.

I believe users on the Startup tier benefit the most. For Enterprise users, considering the monthly cost, it might be more cost-effective in the long term to hire a dedicated developer to manage your documentation platform. This way you can have all your feature sets met instead of dealing with workarounds.

Here is another article you might like 😊 Mermaid tutorial (setup)

Tech Jobs | Newsletter [↗] 🗯️ Got a question?    🔗 Share on 𝕏