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
+199
-62
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",
|
"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."
|
||||||
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
+4
-4
@@ -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
|
||||||

|

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

|

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

|

|
||||||
```
|
```
|
||||||
|
|
||||||
## Code Blocks
|
## Code Blocks
|
||||||
+1
-1
@@ -1,6 +1,6 @@
|
|||||||
{
|
{
|
||||||
"label": "Tutorial - Extras",
|
"label": "Tutorial - Extras",
|
||||||
"position": 3,
|
"position": 2,
|
||||||
"link": {
|
"link": {
|
||||||
"type": "generated-index"
|
"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
|
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#.
|
||||||
@@ -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
-1
@@ -1,6 +1,6 @@
|
|||||||
---
|
---
|
||||||
sidebar_position: 1
|
sidebar_position: 1
|
||||||
title: Purpose & Guidance
|
title: HUB Spec Standard Overview
|
||||||
---
|
---
|
||||||
|
|
||||||
# Purpose & Guidance
|
# 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
|
sidebar_position: 3
|
||||||
title: Custom Fields
|
title: How to Document Custom Fields
|
||||||
---
|
---
|
||||||
|
|
||||||
# Custom Fields Documentation Standard
|
# Custom Fields Documentation Standard
|
||||||
+1
-1
@@ -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
-1
@@ -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
-1
@@ -1,6 +1,6 @@
|
|||||||
---
|
---
|
||||||
sidebar_position: 3
|
sidebar_position: 3
|
||||||
title: Approvals & Deliverables
|
title: Approvals & Deliverables Template
|
||||||
---
|
---
|
||||||
|
|
||||||
# Approvals & Deliverables
|
# Approvals & Deliverables
|
||||||
File renamed without changes.
File renamed without changes.
+1
-1
@@ -1,6 +1,6 @@
|
|||||||
---
|
---
|
||||||
sidebar_position: 2
|
sidebar_position: 2
|
||||||
title: Estimates
|
title: Estimates Template
|
||||||
---
|
---
|
||||||
|
|
||||||
# Estimates
|
# Estimates
|
||||||
File renamed without changes.
File renamed without changes.
+1
-1
@@ -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
@@ -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.
|
|
||||||
@@ -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
@@ -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 |
Reference in new issue
Block a user