We are very excited to announce the availability of the latest version of API Gateway and API Manager documentation in our open-source docs-as-code workflow! We have migrated all the API Gateway and API Manager content (except for a few low priority guides which will follow later).
API Gateway and API Manager documentation are now open source! What does this mean for you?
Anyone can now propose changes to any topic in the AMPLIFY™ API Management or AMPLIFY™ Central documentation using a quick and easy process. All you need is a GitHub account.
To get started go to AMPLIFY API Management and AMPLIFY Central documentation.
Here’s a short animation demonstrating how to make and preview a change with Netlify CMS:
The CMS also allows you to make further updates after sending the changes for review (i.e., to clarify something or to add something you forgot). It’s also the easiest way to add a new topic within an existing section.
For those who have Markdown skills and prefer to use GitHub UI, this option is also provided via an Edit on GitHub button on each page of the documentation. Of course, if you are a Git expert you can also use Git CLI to fork the Axway GitHub repo and submit a pull request. The choice is yours. See the Contribution Guidelines for full details.
What does this mean for customers?
This will be available as an open beta to external customers very soon and it will enable customers to:
- Propose changes to any page in the documentation with the click of a button. All they will need is a GitHub account, they don’t need any special access rights as the repository is public, and they don’t even need to know Markdown if they use the CMS.
- When they send their changes for review, they will receive an email containing a link to a deploy preview. This preview is usually available within less than three minutes and shows them exactly how their changes will look on the live site.
- Every proposed change will be reviewed for clarity and style by a technical writer (and if necessary, by a developer for technical accuracy).
- Customers will be notified by email when their changes are merged and published on doc portal production (note this site currently requires Axway ID login to see non-GA content).
- Customers who don’t want to suggest a change but want to point out an error or give feedback can quickly report an issue with our docs using GitHub issues.
This is the same workflow that many other companies are offering, including Microsoft, AWS, Kubernetes, to name a few. However, our use of a WYSIWYG CMS option is so far unique to Axway, and we believe this opens up our doc to even more potential contributors who don’t have Git or Markdown skills.
What does this mean for writers?
Up to now, technical writers have often been the sole content contributors to the product documentation. We’ve historically used help with authoring tools such as Madcap Flare to produce documentation, but this often meant that due to licensing costs and complex source formats such as XHTML, non-technical writers could not easily contribute directly.
By migrating our documentation to a simple Markdown format, and storing it in a public GitHub repository, we’ve now opened it up to contributions from anyone (internal SMEs or external customers). This means that our role will change from being the sole content creators to content editors and curators.
Instead of having technical writers create content from scratch (or from information spread across a multitude of internal sources such as Confluence, Jira tickets, feature demos, etc.), the SMEs can directly create the content for end-users, and tech writers will review and publish it.
It will now be easier and quicker than ever before to get the most accurate product information out there in front of our customers, as this model allows every person in Axway and every user of our documentation to become a doc contributor.
If you have contributed to our documentation using the new open-source docs-as-code workflow, please fill out our quick Axway Open Documentation Feedback with NPS® Survey to give us feedback and to prioritize the improvements we need to make before we make this available to external customers.
Learn how to set up an API Gateway with AMPLIFY Central.