Hub’s Best Practices
Documentation is a principal driving force for great UX. APIs require basic referential material for consumption, but great UX comes from all of the supplementary information you provide your users. To support the creation of any number of different supplementary documents, images, videos, etc. we created Hubs, our documentation tool. We pushed the limits of API documentation beyond specifications and models to accommodate all of the secondary and tertiary information that can help drive good UX.
Referencing Other Files/ Git Repo for Open Sourcing Docs
Open sourcing your documentation can provide a number of advantages including more engagement and content. Users and businesses often create their own supplemental documents supporting their own unique use cases. By providing a Github repo, these users and companies can contribute their unique documentation to your docs enhancing your UX. Stoplight’s Hubs has a ref builder that allows you to directly reference any markdown and YAML files. Create and store your markdown files in a Github Repo or other file sharing platform and directly reference them in Hubs. This workflow also gives the added benefit of changes made to any markdown files being automatically reflected in your documentation.
Table of Contents
One of Stoplight’s central principles is ‘a single source of truth.’ We applied this principle to Hubs by adding in a ‘Table of Contents.’ The Table of Contents is a bird’s eye view of the structure of your docs that allows you to strategize and manipulate the structure of your docs.
Pages function similarly to chapters in a book. They group similar content together at the broadest scope. We recommend adding pages sparingly to keep your documentation concise and easily navigable. Connect pages via headers in Hub Settings.
If pages are the chapters of a book, subpages are sections within chapters. Create a subpage for each topic you wish to address. The scope should be as narrow as possible to help your users more easily navigate your documentation. New subpages auto-populate the sidebar navigation of a page. Drag and drop in the navigation for structural adjustments and create empty subpages to create navigational headers to further clarify structure.
Integrations are quickly becoming core elements of any platform. Stoplight’s Hubs provides easy integrations to satisfy the most popular builds. Add a Google Analytics integration to track your documentation consumers activity. Integrate Intercom into your documentation to provide additional support. Add a Segment integration for any other integrations supported by Segment.
SEO is important in any content including documentation. Use a Google Analytics integration to optimize your documentation for Google.
Routing ties into SEO but is also an important aspect of a well structured and organized document. Create easily readable routes that identify your content accurately to maximize the SEO of your documentation. Use the ‘Table of Contents’ to view the connections between pages and subpages to make clever use of routes. Add Page tags for additional clarification on what kind of content is housed within.
Documentation design is not just a pretty package for your content. It impacts a number of different aspects of your business including marketing, branding, and UX. Use theming for marketing and branding purposes to make simple global style adjustments. Most businesses have 2-3 primary colors that can be applied to your docs through theming. For more advanced design, use Custom CSS to have complete control of the style of your documentation.