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:
1 parent
2cfb6f5ef7
commit
b9a194f7c5
44 files changed
+200
-63
No files matched your search
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"label": "Contributing",
|
||||
"position": 4,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"description": "Guidelines for contributing to and maintaining this documentation site."
|
||||
}
|
||||
}
|
||||
@@ -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/).
|
||||
@@ -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."
|
||||
}
|
||||
}
|
||||
@@ -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
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"label": "Tutorial - Basics",
|
||||
"position": 2,
|
||||
"position": 1,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"description": "5 minutes to learn the most important Docusaurus concepts."
|
||||
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
+5
-5
@@ -59,18 +59,18 @@ Let's see how to [Create a page](./create-a-page.mdx).
|
||||
|
||||
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
|
||||

|
||||

|
||||
```
|
||||
|
||||

|
||||

|
||||
|
||||
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
|
||||

|
||||

|
||||
```
|
||||
|
||||
## Code Blocks
|
||||
@@ -147,7 +147,7 @@ This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !
|
||||
This is <Highlight color="#1877F2">Facebook blue</Highlight> !
|
||||
```
|
||||
|
||||
export const Highlight = ({children, color}) => (
|
||||
export const Highlight = ({ children, color }) => (
|
||||
<span
|
||||
style={{
|
||||
backgroundColor: color,
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"label": "Tutorial - Extras",
|
||||
"position": 3,
|
||||
"position": 2,
|
||||
"link": {
|
||||
"type": "generated-index"
|
||||
}
|
||||
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -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."
|
||||
}
|
||||
}
|
||||
+5
-1
@@ -1,10 +1,14 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: IFS Integration
|
||||
title: IFS Integration Architecture
|
||||
---
|
||||
|
||||
# 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.
|
||||
|
||||
IFS integration is done via an **IFS Wrapper Module** that works as a low-code representation of the IFS Integration extension written in C#.
|
||||
@@ -1,5 +1,9 @@
|
||||
{
|
||||
"label": "HOIST HUB Documentation Standard",
|
||||
"position": 1,
|
||||
"collapsible": false
|
||||
"position": 3,
|
||||
"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
-1
@@ -1,6 +1,6 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: Purpose & Guidance
|
||||
title: HUB Spec Standard Overview
|
||||
---
|
||||
|
||||
# Purpose & Guidance
|
||||
File renamed without changes.
@@ -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
-1
@@ -1,6 +1,6 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: Custom Fields
|
||||
title: How to Document Custom Fields
|
||||
---
|
||||
|
||||
# Custom Fields Documentation Standard
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: Mockups & Screenshots
|
||||
title: How to Document Mockups & Screenshots
|
||||
---
|
||||
|
||||
# Mockups & Screenshots Documentation Standard
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: UI Flow Development
|
||||
title: How to Document a UI Flow
|
||||
---
|
||||
|
||||
# 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
-1
@@ -1,6 +1,6 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: Approvals & Deliverables
|
||||
title: Approvals & Deliverables Template
|
||||
---
|
||||
|
||||
# Approvals & Deliverables
|
||||
File renamed without changes.
File renamed without changes.
+1
-1
@@ -1,6 +1,6 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: Estimates
|
||||
title: Estimates Template
|
||||
---
|
||||
|
||||
# Estimates
|
||||
File renamed without changes.
File renamed without changes.
+1
-1
@@ -1,6 +1,6 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: Test Plan
|
||||
title: Test Plan Template
|
||||
---
|
||||
|
||||
# Test Plan
|
||||
@@ -1,4 +0,0 @@
|
||||
{
|
||||
"label": "Specification",
|
||||
"position": 4
|
||||
}
|
||||
+23
-25
@@ -1,47 +1,45 @@
|
||||
---
|
||||
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:
|
||||
- When installing Node.js, you are recommended to check all checkboxes related to dependencies.
|
||||
- **IFS Integration Architecture** — How HOIST HUB communicates with IFS via the generic wrapper module, including available server actions and key data structures
|
||||
|
||||
## 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
|
||||
npm init docusaurus@latest my-website classic
|
||||
```
|
||||
- **Explanation** — Understand the purpose of the standard and the roles involved
|
||||
- **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.
|
||||
Reference in new issue
Block a user