A specialist documentation platform, within an enterprise documentation system, is one that is optimized to produce and browse information that is relevant to a specific functional area (e.g., IT), vertical domain (e.g., UI/UX), or specific subject matter. DocOps efforts typically focus on integrating the content from said platforms onto the main documentation platform and vice versa.
A non-exhaustive subcategorization of specialist IT-oriented documentation platforms includes:
- Domain-specific authoring tools: they focus on the description of domain-specific artifacts, typically using a pictorial-centric approach. BPMN editors are a good example of this category.
- API portals: they focus on optimizing the discovery and browsing of network (REST, GraphQL, etc.) and language APIs (C#, Java, etc.)
- Developer portals: they focus on the documentation use cases pertaining the description of engineered products (e.g., software) or services. Given that they extract documentation directly from IT assets, they offer high adherence to the principles of generative content and truth proximity, but they suffer in terms of fostering a culture of shared responsibility given that they split documentation communities into technical and non-technical ones.
- Business Intelligence Portals: they act as the front-end for the output of analytical systems, which are systems of facts.
Limitations
Introducing specialist documentation platforms may present a number of challenges, unless managed effectively:
- Lack of general-purpose documentation platform: Enterprises that lack a proper main documentation platform may inadvertently treat the specialist documentation platform as a general-purpose documentation platform, resulting in a degraded enterprise documentation experience far removed from documentation systems tenets.
- Integration barriers: Specialist documentation platforms often don’t see themselves as members of a wider documentation system, resulting in the need of spending significant DocOps engineering efforts to integrate them:
- The platform may not support SSO, requiring a DocOps workaround to link credential systems
- The platform may not share its assets (text, images, etc) in an open format, requiring a DocOps workaround to extract said assets—ranging from direct database interaction to screen scraping.
- The platform may be dashboard-centric, making it difficult to link up scattered content assets into a semantically coherent document.
- Poor adherence to the principle of shared responsibility: Many specialist platforms are available to a limited audience for reasons such as:
- Limited number of licences
- The need to install and run executable files which may be: