API Builder Docs is a docs-as-code implementation for Axway documentation. It is built using the Hugo static site generator with the Google Docsy theme.
This repository contains all files for building and deploying the site. The Markdown files for the documentation are stored at /content/en/docs. The image files for the documentation are stored at /static/Images.
We welcome your contributions! To get started fork this repository, create a feature branch with your changes, and then submit a pull request.
Titles are sentence-case where proper nouns and acronymns are capitalized.
API Builder style guide
Check your API
When referencing a document by title, then the link must use the title capitalization (which is sentence-case, not camel-case), e.g.:
Refer to API Builder style guide for more information.
When making a general ad-hoc reference that is not the same as the title, then use capitalization as sentence context case dictates.
When making links in documents, ensure you follow the rules.
When writing about text buttons, these shall be Bold, and written exactly as they appear in the UI.
- Apply
- Close
- Discard changes
When writing about named inputs, e.g. Status, they should be written in bold and exactly as they appear in the UI.
- Status
- Outputs
These are written in italic
- Change the Selector drop-own to Object.
- Enter
$.outputin Save output value as: - Click the Pencil icon.
Component types are not capitalized, unless they are acronyms. Follow normal capitalization rules for sentences, e.g. within sentences:
- API
- endpoints
- flow
- flow editor
- flow-node
- flow-trigger
- model
As section headings:
- Flow
- Flow editor
- Flow-node
- Flow-trigger
Named plugins shall be bold, but only the name, not the type.
- OpenAPI flow-trigger
- Kafka Consumer flow-trigger
- Kafka Producer flow-node
Pages, such as API Doc & Test shall be written in italic, and exactly as they appear in the UI.
We record animated GIFs for better visualization of process in the docs. We should be consistent when recording though, so everyone should follow the same steps to ensure that the docs look uniform and the animations are a reasonable file size.
Tools:
GIF properties:
- 1240x720
- 5fps
- Infinite repeat count
- The cursor is displayed
- The entire viewport is recorded, but not the browser itself
- Browser is at 100% zoom
Ensure LICEcap is set to the correct fps and image size. This should be persisted, so only need to set it once.
Install and configure Window resizer. I recommend setting a preset for API Builder recording.
Ensure your resize target is viewport, and your width and height are 1240x720.
The most annoying part of this is lining up the chrome window and LICEcap window. Click "use current" when configuring the Window resizer preset. This will allow you to keep the chrome window aligned with your LICEcap window in order to avoid having to reposition it to link up.
You may also need to open the console in your browser to stop the bottom edges being curved. You may also want to use the built-in magnifier (zoom on Mac) to ensure the recording viewport lines up correctly.
When clicking record in LICEcap, ensure the following settings are configured.
