diff --git a/docs/contributing/_category_.json b/docs/contributing/_category_.json new file mode 100644 index 0000000..6560c02 --- /dev/null +++ b/docs/contributing/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Contributing", + "position": 4, + "link": { + "type": "generated-index", + "description": "Guidelines for contributing to and maintaining this documentation site." + } +} diff --git a/docs/contributing/diataxis-framework.md b/docs/contributing/diataxis-framework.md new file mode 100644 index 0000000..9f70362 --- /dev/null +++ b/docs/contributing/diataxis-framework.md @@ -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/). diff --git a/docs/docusaurus-guide/_category_.json b/docs/docusaurus-guide/_category_.json new file mode 100644 index 0000000..62f50c1 --- /dev/null +++ b/docs/docusaurus-guide/_category_.json @@ -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." + } +} diff --git a/docs/docusaurus-guide/intro.mdx b/docs/docusaurus-guide/intro.mdx new file mode 100644 index 0000000..88f9571 --- /dev/null +++ b/docs/docusaurus-guide/intro.mdx @@ -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. diff --git a/docs/tutorial-basics/_category_.json b/docs/docusaurus-guide/tutorial-basics/_category_.json similarity index 90% rename from docs/tutorial-basics/_category_.json rename to docs/docusaurus-guide/tutorial-basics/_category_.json index 2e6db55..79e99bc 100644 --- a/docs/tutorial-basics/_category_.json +++ b/docs/docusaurus-guide/tutorial-basics/_category_.json @@ -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." diff --git a/docs/tutorial-basics/congratulations.mdx b/docs/docusaurus-guide/tutorial-basics/congratulations.mdx similarity index 100% rename from docs/tutorial-basics/congratulations.mdx rename to docs/docusaurus-guide/tutorial-basics/congratulations.mdx diff --git a/docs/tutorial-basics/create-a-blog-post.mdx b/docs/docusaurus-guide/tutorial-basics/create-a-blog-post.mdx similarity index 100% rename from docs/tutorial-basics/create-a-blog-post.mdx rename to docs/docusaurus-guide/tutorial-basics/create-a-blog-post.mdx diff --git a/docs/tutorial-basics/create-a-document.mdx b/docs/docusaurus-guide/tutorial-basics/create-a-document.mdx similarity index 100% rename from docs/tutorial-basics/create-a-document.mdx rename to docs/docusaurus-guide/tutorial-basics/create-a-document.mdx diff --git a/docs/tutorial-basics/create-a-page.mdx b/docs/docusaurus-guide/tutorial-basics/create-a-page.mdx similarity index 100% rename from docs/tutorial-basics/create-a-page.mdx rename to docs/docusaurus-guide/tutorial-basics/create-a-page.mdx diff --git a/docs/tutorial-basics/deploy-your-site.mdx b/docs/docusaurus-guide/tutorial-basics/deploy-your-site.mdx similarity index 100% rename from docs/tutorial-basics/deploy-your-site.mdx rename to docs/docusaurus-guide/tutorial-basics/deploy-your-site.mdx diff --git a/docs/tutorial-basics/markdown-features.mdx b/docs/docusaurus-guide/tutorial-basics/markdown-features.mdx similarity index 92% rename from docs/tutorial-basics/markdown-features.mdx rename to docs/docusaurus-guide/tutorial-basics/markdown-features.mdx index 3085337..2d74ae2 100644 --- a/docs/tutorial-basics/markdown-features.mdx +++ b/docs/docusaurus-guide/tutorial-basics/markdown-features.mdx @@ -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 -![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: ```md -![Docusaurus logo](./img/hoist-partner-logo.png) +![Docusaurus logo](./img/hoist-logo.avif) ``` ## Code Blocks @@ -147,7 +147,7 @@ This is Docusaurus green ! This is Facebook blue ! ``` -export const Highlight = ({children, color}) => ( +export const Highlight = ({ children, color }) => (
+ HOIST Logo {siteConfig.title}

{siteConfig.tagline}

+ to="/docs/intro"> Get Started
diff --git a/static/img/White Hoist Logo.avif b/static/img/hoist-logo.avif similarity index 100% rename from static/img/White Hoist Logo.avif rename to static/img/hoist-logo.avif diff --git a/static/img/hoist-partner-logo.png b/static/img/hoist-partner-logo.png deleted file mode 100644 index 5417f12..0000000 Binary files a/static/img/hoist-partner-logo.png and /dev/null differ