In Part 1, we unraveled the diverse documentation types essential for a robust developer portal, understanding that content variety is key to meeting the distinct needs of various consumers. We recognized that the efficiency of content creation hinges on a tailored publication environment.
Now we explore how the Zero Gravity Developer Portal addresses the requirements of both technical and non-technical content creators, ensuring an effective content management experience.
Table of contents:
- From no-code to full-automation
- No-Code Page Creation: Crafting Consistent and Polished Content Without Touching Code
- Content Types: Tailored Templates for Varied Needs
- API Reference: Empowering Developers and Technical Writers
- Building pages around API reference documentation
- Beyond APIs: Editorial Frameworks for Varied Content
- Editing Flexibility: WYSIWYG and Markdown Options
- Version Control: Safeguarding Content Integrity
- Drafts and Content Moderation: Fine-Tuning Content Workflow
- Access Control: Ensuring Safety and Security
- What you see is what you get - The CMS-way
- Going Beyond: Markdown Content
- Next Level: CI/CD Content Management
- When You Outgrow Out-of-the-Box: Custom Solutions for Complex Content Needs
- Conclusion: Unifying Content and Workflow in the Developer Portal Landscape
- Related reading
- Part1: How Zero Gravity Developer Portal Enhances Content Management. Effective content management is as crucial as writing code
From no-code to full-automation
Zero Gravity, as it is built upon the Drupal Content Management System (CMS), emerges as a powerful ally for stakeholders involved in your developer portal project.
To create pages with complex content structure, Zero Gravity provides page builder elements that allow content editors to combine various components for an appealing design. Alternatively, if your content team prefers, it is possible to create pages from Markdown content. This flexibility allows you to upload and manage — last but not least — API documentation bundles through a CI/CD pipeline without interacting with the user interface.
No-Code Page Creation: Crafting Consistent and Polished Content Without Touching Code
Content Types: Tailored Templates for Varied Needs
Zero Gravity comes equipped with a selection of page forms, called content types in Drupal’s terminology. Each content type serves as a specialized template catering to different and specific content requirements. This default set of content types is designed to encompass virtually all the content needs essential for a developer portal.
API Reference: Empowering Developers and Technical Writers
The API Reference content type takes center stage for API developers and technical writers. It facilitates the upload of OpenAPI Specification (OAS) files or the manual creation of API reference documentation pages. With the choice of the built-in WYSIWYG (What You See Is What You Get) text editor or Markdown content upload, users can precisely tailor their documentation.
Whenever an API content creator publishes an API reference page on the portal, Zero Gravity automatically creates a respective card in a dedicated API Catalog showcasing the provided API-related information in a user-friendly way.
Building pages around API reference documentation
On its own, API reference documentation isn’t enough. While it is perfect for technical users, business personas or even tech-savvy decision-makers often require an approach to quickly find solutions to their needs. Zero Gravity enables the extension of API reference documentation pages to cater to a diverse audience.
API Description or Summary Page
To address the needs of non-technical users, we advise you to provide a high-level overview for quick consumption. Include a benefit section highlighting key features, followed by a concise introduction answering the "What is it?" question. Explain why users should choose the API and what they can achieve with it. The "How to use" section should guide users through the initial steps, offering links to registration or the get-started page. If there are usage restrictions, create a "Requirements" section. Conclude with a call to action, providing links to request an API key.
Tutorials or Use Cases
Tutorials and use cases are invaluable for users seeking practical guidance. Consider creating step-by-step tutorials showcasing real-world scenarios where the API can be applied. Provide clear instructions, code snippets, and expected outcomes to assist users in understanding the practical applications of your API.
Release Notes
You can keep users informed with regular release notes. Share details about updates, new features, improvements, and bug fixes. Offer a chronological overview of changes, making it easy for users to track the evolution of the API. Highlight any backward compatibility considerations, deprecated features, or actions users need to take after an update.
Beyond APIs: Editorial Frameworks for Varied Content
Apart from API reference, Zero Gravity provides various other content types, each offering an editorial framework. These frameworks cater to diverse content needs, including landing pages, blog posts, onboarding materials, support pages, FAQ items, and legal documents.
Editing Flexibility: WYSIWYG and Markdown Options
Zero Gravity enhances flexibility by providing multiple text format options. Content creators can use the built-in text editor, paste content from their preferred platforms, or upload Markdown content.
Version Control: Safeguarding Content Integrity
Zero Gravity stands out with its built-in version control, exposing all saved changes through a dedicated administrative page. This feature allows administrators to revert to an earlier state if unexpected issues arise, ensuring the integrity of the portal's content.
Drafts and Content Moderation: Fine-Tuning Content Workflow
Content creators can save incomplete pages as drafts, keeping them concealed from portal users until finalized. For those seeking a more sophisticated content moderation workflow, more complex configurations can be provided.
Access Control: Ensuring Safety and Security
Zero Gravity's granular access control system is a cornerstone for ensuring the safety and security of the CMS. This system empowers administrators to manage user permissions and control content access effectively.
What you see is what you get - The CMS-way
CMS Environment for Content Crafting
Zero Gravity provides an intuitive environment for crafting and managing content. For content creators, especially those without extensive technical backgrounds, it offers a built-in WYSIWYG text editor, simplifying the content creation process. In addition, Zero Gravity has different content types that are like ready-made templates for specific content needs.
Contributors can create pages with complex structures using the platform's page builder. This feature lets the content creators put together attractive designs by combining different elements. When making onboarding pages with sidebar navigation, content creators just need to focus on the content, and the system takes care of building the knowledge hub. Plus, Zero Gravity handles the maintenance of the API catalog and the FAQ or Support page, automatically adding API cards and new FAQ items to the right categories.
Similarity to Popular Platforms
The built-in text editor, akin to widely used platforms such as Microsoft Word and Google Docs, provides content creators with a familiar toolkit. Its design closely mirrors the functionalities of these popular platforms, ensuring an intuitive experience for writers and editors.
Collaborative Editing in Drupal Core
Collaborative editing for Drupal 10 is on the horizon. Using open-source tools, the Edit Together module provides secure, real-time collaboration inside the Drupal editorial interface. Editors may update content simultaneously and leave threaded comments requesting clarifications or changes.
Alignment with Design Guidelines
One of the key advantages of Zero Gravity’s built-in text editor is its alignment with the design guidelines of your company. This adherence to preset design parameters ensures a consistent look and feel across all created content. Writers and editors can easily utilize the editor to incorporate various elements into their content, such as buttons, images, tables, and more, ensuring a professional and uniform appearance.
Seamless Transition for External Editors
For those who prefer working in their favorite text editors like Word, Confluence, or Google Docs, Zero Gravity allows a seamless transition. Writers can compose content in their chosen external editor and then paste it into the text editor field. The system then applies the preset formatting, maintaining a cohesive appearance.
This flexibility ensures that content creators can leverage their preferred tools while upholding a unified and visually appealing presentation on the Zero Gravity developer portal.
Going Beyond: Markdown Content
A Lightweight Markup Language for Streamlined Content Creation
Markdown files, being plain text, offer compatibility across various platforms and collaborative writing tools, promoting easy sharing and collaboration. Markdown's efficiency extends to its use with version control systems like Git, facilitating tracking and management. The focus on content rather than intricate formatting, as well as its extensibility through custom tags, makes Markdown a preferred choice for technical writers and developers.
GitHub-Flavored Markdown in WYSIWYG Editor
Zero Gravity offers a GitHub-flavored Markdown text format option, allowing content creators to upload Markdown content. The system renders it according to design guidelines.
Bridging the Gap
This feature bridges the gap between content creators using collaborative writing platforms and those closely working with developers. Developers also can contribute using their preferred tools.
Enhancing Collaboration
API reference pages, while crucial, might not serve all consumer needs. GitHub-flavored Markdown support enables developers to collaborate with other content creators by creating drafts alongside API reference pages.
Documentation CI/CD Pipeline
The GitHub-flavored Markdown support paves the way to a documentation Continuous Integration and Continuous Deployment (CI/CD) pipeline. Content creators can push and manage content without interacting with the user interface.
Complex Page Layouts with Markdown
Complex page layouts can be created purely from Markdown files. The system interprets HTML codes around the Markdown syntax. Best practice involves using custom tags that a script can convert into complex HTML during the upload process, either if it happens manually or through CI/CD.
Next Level: CI/CD Content Management
Continuous Integration and Continuous Deployment (CI/CD) represents a methodology that streamlines and automates the process of content deployment, providing a code-centric approach to content management.
Integration with CI/CD Pipelines & Benefits of a Code-Centric Approach
CI/CD integration provides developers with an organized and automated workflow for deploying content. By leveraging CI/CD pipelines, developers can efficiently push content updates without the need for manual intervention.
One of the key components of this integration is Zero Gravity's utilization of JSON:API. This feature provides content creators with endpoints, establishing a direct channel through which they can interact with the CMS. These endpoints empower users to manage both content and content-related metadata on the developer portal.
Establishing a Documentation Hub from Documentation Islands
Leveraging a CI/CD pipeline not only simplifies content management but also acts as a bridge connecting various representatives from different fields involved in a developer portal project.
It transforms the documentation approach from an isolated island, primarily focused on source and reference documentation, into a centralized Documentation Hub. This hub consolidates diverse content types, catering not only to developers but also to other stakeholders by presenting everything in one accessible location. The CI/CD pipeline becomes a crucial facilitator in unifying efforts and ensuring the success of a comprehensive developer portal project.
When You Outgrow Out-of-the-Box: Custom Solutions for Complex Content Needs
Empowering Multilingual Engagement
As your company expands globally, it's crucial to accommodate the preferences of your diverse global audience. With Zero Gravity powered by Drupal, you have all the necessary tools to manage content in multiple languages.
You can configure languages and determine their application across your site, ensuring a seamless experience for users worldwide. Translate everything from pages and menus to user profiles, with full control over which content is translated and how it is presented.
As you can read on Drupal’s website, “You can decide whether each type of content entity (pages, comments, custom blocks, taxonomy terms, user accounts, etc.) should be translatable or not. Then, within each entity type, you can decide whether the sub-types (content types for node page content, terms in particular vocabularies for taxonomy, etc.) should be translated. Within each translatable entity sub-type, you can decide which fields should be translatable.”
The built-in translation management tools make it easy to locate and translate content, while automatic assistance streamlines the retrieval of translations. For languages where translation has already been completed, you can apply translations by setting up a module.
Drupal provides a comprehensive solution for reaching global audiences with multilingual content, simplifying the process of engaging users in their preferred language.
Integration with Ticketing Systems
Zero Gravity provides the capability to integrate with various ticketing systems. This functionality allows developer portal users to create issues directly on the portal. Administrators can then manage these issues through the portal's administration UI, while support members can address and resolve issues within their own environment.
Extending the API Catalog with Advanced Search Options
Zero Gravity's default API catalog can be enhanced with advanced search functionalities, including keyword search and multi-level tagging. This extension allows for a more refined and efficient exploration of content within the catalog.
Diversifying Catalogs for Varied Content
Zero Gravity offers flexibility in extending catalogs beyond APIs, allowing for the inclusion of Use Cases, Case Studies, Partner Showcases, or Testimonials. Each catalog can have a dedicated content type, ensuring a unique yet unified appearance. The system automatically populates catalogs when pages are created with related content types.
Showcasing Featured Items on Landing Pages
To highlight key content, Zero Gravity enables the listing of featured items from each catalog directly on landing pages. This feature enhances visibility and accessibility to noteworthy content for users.
Organizing Products and Product Groups
For organizations seeking a structured presentation of services, Zero Gravity allows the organization of APIs, SDKs, and Widgets into Products, or Products into Product Groups. Pronovix’s UX team is available to assist in mapping the best solutions for showcasing a comprehensive palette of services in a user-friendly manner.
Conclusion: Unifying Content and Workflow in the Developer Portal Landscape
As we navigated through the intricacies of developer portals, we uncovered the diverse needs and expectations of different personas, forming a comprehensive inventory of consumer requirements. In recognizing the varied landscape of developer portals, we emphasized the crucial role of providing a unified, familiar environment for content creation to cater to all consumers. Our exploration aimed to steer clear of documentation islands, highlighting the necessity of achieving a documentation hub that seamlessly serves the needs of all stakeholders.
Zero Gravity emerged as a unifying force in this landscape, blending user-friendly content creation with a developer-centric workflow. Our showcase of Zero Gravity's content publication and management services underscored its capability to evolve with the maturity of your developer portal project, accommodating the growth of your team and products.
Whether you're embarking on a new developer portal journey or refining an existing one, Pronovix offers onboarding content management sessions.
Our commitment extends beyond providing a solution; Pronovix offers a collaborative partnership to ensure your developer portal project's success. With services ranging from technical writing assistance to UX team support, we understand that each company and project is unique. Pronovix is dedicated to fostering a long-term collaboration to help you achieve your goals in the realm of developer portals.
Do you already have a devportal? Or are you just building one? Are you looking for help with a specific UX task?
Do you want to improve the onboarding experience on your developer portal? Is there room for improvement with your technical documentation?
Related reading
If we piqued your interest and you would like to read more about developer portal components, developer portal maturity, unified documentation experience, docs-as-code, and API documentation tools here are some helpful links.
- What is the Difference Between API Documentation and a Developer Portal?
- Components of a developer portal
- Maturity model for developer portals
- One Developer Portal to Document Them All
- Consolidate & Govern Part 1: Scaling Docs-as-code For Enterprise
- Consolidate & Govern Part 2: Republishing Docs-as-Code Content With a Developer Hub CMS
- CI/CD and Docs-as-Code workflow
- How to Improve DocOps using CI/CD and Docs-as-Code
- Free and Open Source API Documentation Tools
- Reference Pages
All Pronovix publications are the fruit of a team effort, enabled by the research and collective knowledge of the entire Pronovix team. Our ideas and experiences are greatly shaped by our clients and the communities we participate in.
