docs: reorganize site structure using Diátaxis framework

- Group hub-documentation into explanation/, how-to/, and reference/ per Diátaxis
- Move ifs-integration.md to new hoist-hub/ category
- Add contributing/ category with Diátaxis framework explainer
- Move tutorial-basics and tutorial-extras under docusaurus-guide/
- Rewrite docs/intro.mdx as site entry point with category navigation
- Update all doc titles to reflect their Diátaxis type
- Add HOIST logo to homepage hero and fix Get Started link
This commit is contained in:
jaime.meza committed 2026-06-18 14:50:15 -05:00
1 parent 2cfb6f5ef7
commit b9a194f7c5
44 files changed
+199 -62

No files matched your search

+8
View File
@@ -0,0 +1,8 @@
{
"label": "Contributing",
"position": 4,
"link": {
"type": "generated-index",
"description": "Guidelines for contributing to and maintaining this documentation site."
}
}
+38
View File
@@ -0,0 +1,38 @@
---
sidebar_position: 3
title: Documentation Framework (Diátaxis)
---
# Documentation Framework (Diátaxis)
This documentation site is structured using the [Diátaxis framework](https://diataxis.fr/) — a systematic approach to technical documentation that organizes content around user needs rather than product structure.
## The Core Idea
Documentation serves different purposes depending on what the reader needs at a given moment. Diátaxis identifies four distinct needs and maps them to four types of documentation:
| Type | Answers | Reader is... |
|---|---|---|
| **Explanation** | "Why does this work this way?" | Seeking understanding |
| **How-to Guide** | "How do I accomplish X?" | Solving a specific problem |
| **Reference** | "What exactly does this field/section require?" | Consulting while working |
| **Tutorial** | "How do I learn this from scratch?" | Learning for the first time |
## How This Site Uses Diátaxis
### Explanation
Content that provides context, background, and reasoning. Read this to understand the *why* behind the HUB Spec Standard — its purpose, the roles involved, and the architectural decisions behind IFS integration.
### How-to Guides
Step-by-step guidance for specific documentation tasks. Read these when you know *what* you need to document but need direction on *how* to do it correctly — such as documenting a UI flow, mockups, or custom fields.
### Reference
Templates and structural standards for every section of a HUB spec. Consult these *while writing* a spec — they define what each section must contain, what fields are required, and how tables should be structured.
## Why This Matters
Mixing documentation types is one of the most common causes of poor documentation. A reference page that tries to also teach and guide becomes hard to navigate. A how-to guide bloated with background theory loses its usefulness when someone needs a quick answer.
By keeping each type separate and clearly labeled, every reader — whether a new Business Analyst or an experienced Developer — can find exactly what they need without reading everything.
For a deeper understanding of the framework, visit [diataxis.fr](https://diataxis.fr/).
+8
View File
@@ -0,0 +1,8 @@
{
"label": "Docusaurus Guide",
"position": 5,
"link": {
"type": "generated-index",
"description": "Learn how to work with Docusaurus — create pages, write docs, manage versions, and deploy the site."
}
}
+47
View File
@@ -0,0 +1,47 @@
---
sidebar_position: 1
---
# Tutorial Intro
Let's discover **Docusaurus in less than 5 minutes**.
## Getting Started
Get started by **creating a new site**.
Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**.
### What you'll need
- [Node.js](https://nodejs.org/en/download/) version 20.0 or above:
- When installing Node.js, you are recommended to check all checkboxes related to dependencies.
## Generate a new site
Generate a new Docusaurus site using the **classic template**.
The classic template will automatically be added to your project after you run the command:
```bash
npm init docusaurus@latest my-website classic
```
You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
The command also installs all necessary dependencies you need to run Docusaurus.
## Start your site
Run the development server:
```bash
cd my-website
npm run start
```
The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.
The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes.
@@ -1,6 +1,6 @@
{ {
"label": "Tutorial - Basics", "label": "Tutorial - Basics",
"position": 2, "position": 1,
"link": { "link": {
"type": "generated-index", "type": "generated-index",
"description": "5 minutes to learn the most important Docusaurus concepts." "description": "5 minutes to learn the most important Docusaurus concepts."
@@ -59,18 +59,18 @@ Let's see how to [Create a page](./create-a-page.mdx).
Regular Markdown images are supported. Regular Markdown images are supported.
You can use absolute paths to reference images in the static directory (`static/img/hoist-partner-logo.png`): You can use absolute paths to reference images in the static directory (`static/img/hoist-logo.avif`):
```md ```md
![Docusaurus logo](/img/hoist-partner-logo.png) ![Docusaurus logo](/img/hoist-logo.avif)
``` ```
![Docusaurus logo](/img/hoist-partner-logo.png) ![Docusaurus logo](/img/hoist-logo.avif)
You can reference images relative to the current file as well. This is particularly useful to colocate images close to the Markdown files using them: You can reference images relative to the current file as well. This is particularly useful to colocate images close to the Markdown files using them:
```md ```md
![Docusaurus logo](./img/hoist-partner-logo.png) ![Docusaurus logo](./img/hoist-logo.avif)
``` ```
## Code Blocks ## Code Blocks
@@ -1,6 +1,6 @@
{ {
"label": "Tutorial - Extras", "label": "Tutorial - Extras",
"position": 3, "position": 2,
"link": { "link": {
"type": "generated-index" "type": "generated-index"
} }
+8
View File
@@ -0,0 +1,8 @@
{
"label": "HOIST HUB",
"position": 2,
"link": {
"type": "generated-index",
"description": "Technical documentation for the HOIST HUB platform — architecture, integrations, and platform standards."
}
}
@@ -1,10 +1,14 @@
--- ---
sidebar_position: 1 sidebar_position: 1
title: IFS Integration title: IFS Integration Architecture
--- ---
# Integration with IFS # Integration with IFS
:::danger
Documentation versioning with git
:::
Integration with IFS is a crucial part of HOIST Hub Design. Most HOIST HUB applications function in conjunction with or on top of IFS data sources. Therefore, tight IFS integration is required for most projects. Integration with IFS is a crucial part of HOIST Hub Design. Most HOIST HUB applications function in conjunction with or on top of IFS data sources. Therefore, tight IFS integration is required for most projects.
IFS integration is done via an **IFS Wrapper Module** that works as a low-code representation of the IFS Integration extension written in C#. IFS integration is done via an **IFS Wrapper Module** that works as a low-code representation of the IFS Integration extension written in C#.
+6 -2
View File
@@ -1,5 +1,9 @@
{ {
"label": "HOIST HUB Documentation Standard", "label": "HOIST HUB Documentation Standard",
"position": 1, "position": 3,
"collapsible": false "collapsible": true,
"link": {
"type": "generated-index",
"description": "The standard that defines how HUB specs are written, structured, and approved."
}
} }
@@ -1,4 +0,0 @@
{
"label": "Delivery & Governance",
"position": 5
}
@@ -0,0 +1,8 @@
{
"label": "Explanation",
"position": 1,
"link": {
"type": "generated-index",
"description": "Understand the why behind the HOIST HUB standard — roles, purpose, and architectural decisions."
}
}
@@ -1,6 +1,6 @@
--- ---
sidebar_position: 1 sidebar_position: 1
title: Purpose & Guidance title: HUB Spec Standard Overview
--- ---
# Purpose & Guidance # Purpose & Guidance
@@ -0,0 +1,8 @@
{
"label": "How-to Guides",
"position": 2,
"link": {
"type": "generated-index",
"description": "Step-by-step guidance on how to document each section of a HUB spec correctly."
}
}
@@ -1,6 +1,6 @@
--- ---
sidebar_position: 3 sidebar_position: 3
title: Custom Fields title: How to Document Custom Fields
--- ---
# Custom Fields Documentation Standard # Custom Fields Documentation Standard
@@ -1,6 +1,6 @@
--- ---
sidebar_position: 2 sidebar_position: 2
title: Mockups & Screenshots title: How to Document Mockups & Screenshots
--- ---
# Mockups & Screenshots Documentation Standard # Mockups & Screenshots Documentation Standard
@@ -1,6 +1,6 @@
--- ---
sidebar_position: 1 sidebar_position: 1
title: UI Flow Development title: How to Document a UI Flow
--- ---
# UI Flow Development # UI Flow Development
@@ -1,4 +0,0 @@
{
"label": "IFS Integration",
"position": 3
}
@@ -1,4 +0,0 @@
{
"label": "Overview",
"position": 1
}
@@ -1,4 +0,0 @@
{
"label": "Process Standards",
"position": 2
}
@@ -0,0 +1,8 @@
{
"label": "Reference",
"position": 3,
"link": {
"type": "generated-index",
"description": "Templates, field definitions, and structural standards for every section of a HUB spec."
}
}
@@ -1,6 +1,6 @@
--- ---
sidebar_position: 3 sidebar_position: 3
title: Approvals & Deliverables title: Approvals & Deliverables Template
--- ---
# Approvals & Deliverables # Approvals & Deliverables
@@ -1,6 +1,6 @@
--- ---
sidebar_position: 2 sidebar_position: 2
title: Estimates title: Estimates Template
--- ---
# Estimates # Estimates
@@ -1,6 +1,6 @@
--- ---
sidebar_position: 1 sidebar_position: 1
title: Test Plan title: Test Plan Template
--- ---
# Test Plan # Test Plan
@@ -1,4 +0,0 @@
{
"label": "Specification",
"position": 4
}
+23 -25
View File
@@ -1,47 +1,45 @@
--- ---
sidebar_position: 1 sidebar_position: 1
title: Welcome
--- ---
# Tutorial Intro # HOIST HUB Docs
Let's discover **Docusaurus in less than 5 minutes**. This site is the central reference for everyone involved in designing, documenting, and delivering HOIST HUB features — Business Analysts, Developers, and Project Managers.
## Getting Started Use the sections below to find what you need.
Get started by **creating a new site**. ---
Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**. ## [HOIST HUB](/docs/hoist-hub/ifs-integration)
### What you'll need Technical documentation for the HOIST HUB platform itself.
- [Node.js](https://nodejs.org/en/download/) version 20.0 or above: - **IFS Integration Architecture** — How HOIST HUB communicates with IFS via the generic wrapper module, including available server actions and key data structures
- When installing Node.js, you are recommended to check all checkboxes related to dependencies.
## Generate a new site ---
Generate a new Docusaurus site using the **classic template**. ## [HOIST HUB Documentation Standard](/docs/hub-documentation/explanation/purpose)
The classic template will automatically be added to your project after you run the command: The standard that defines how HUB specs are written, structured, and approved. If you are authoring or reviewing a HUB spec, start here.
```bash - **Explanation** — Understand the purpose of the standard and the roles involved
npm init docusaurus@latest my-website classic - **How-to Guides** — Step-by-step guidance on documenting UI flows, mockups, and custom fields
``` - **Reference** — Templates for every section of a HUB spec: business requirements, functional and technical design, test plans, estimates, approvals, and change log
You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor. ---
The command also installs all necessary dependencies you need to run Docusaurus. ## [Contributing](/docs/contributing/diataxis-framework)
## Start your site Guidelines for anyone adding or maintaining content on this site.
Run the development server: - **Documentation Framework (Diátaxis)** — The framework used to organize this site and how to apply it when creating new documentation
```bash ---
cd my-website
npm run start
```
The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there. ## [Docusaurus Guide](/docs/docusaurus-guide/intro)
The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/. Learn how to work with Docusaurus — the tool that powers this site.
- Create pages, write docs, manage versions, and deploy the site
Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes.
+13
View File
@@ -30,14 +30,27 @@
transition: background-color 0.2s, color 0.2s; transition: background-color 0.2s, color 0.2s;
} }
[data-theme='dark'] .heroBanner :global(.button--primary) {
color: var(--hoist-primary-900);
}
.heroBanner :global(.button--primary:hover) { .heroBanner :global(.button--primary:hover) {
background-color: transparent; background-color: transparent;
border-color: #fff; border-color: #fff;
color: #fff; color: #fff;
} }
.heroLogo {
width: 180px;
margin-bottom: 1.5rem;
}
@media screen and (max-width: 996px) { @media screen and (max-width: 996px) {
.heroBanner { .heroBanner {
padding: 4rem 2rem; padding: 4rem 2rem;
} }
.heroLogo {
width: 120px;
}
} }
+6 -1
View File
@@ -14,13 +14,18 @@ export default function Home(): ReactNode {
description="Technical documentation for HOIST HUB implementations"> description="Technical documentation for HOIST HUB implementations">
<header className={styles.heroBanner}> <header className={styles.heroBanner}>
<div className="container"> <div className="container">
<img
src="/img/hoist-logo.avif"
alt="HOIST Logo"
className={styles.heroLogo}
/>
<Heading as="h1" className="hero__title"> <Heading as="h1" className="hero__title">
{siteConfig.title} {siteConfig.title}
</Heading> </Heading>
<p className="hero__subtitle">{siteConfig.tagline}</p> <p className="hero__subtitle">{siteConfig.tagline}</p>
<Link <Link
className="button button--primary button--lg" className="button button--primary button--lg"
to="/docs/hub-documentation/overview/purpose"> to="/docs/intro">
Get Started Get Started
</Link> </Link>
</div> </div>
File renamed without changes.
Binary file not shown.

Before

Width:  |  Height:  |  Size: 15 KiB