Fusion Help Docs

equinor/fusion-skills/skills/fusion-help-docs

作者 equinore8fd6cfaf8edMIT2 個星標收錄於 2026年10月8日更新於 2026年10月8日儲存庫今天更新

Guides app teams through authoring, structuring, and publishing help documentation (articles, release notes, FAQs) using the fusion-help-cli. USE FOR: write help articles, create release notes, set up help docs, publish documentation, sync articles, configure help config file, maintain app help content. DO NOT USE FOR: building the CLI itself, modifying Fusion.Services.Help internals, or non-documentation tasks.

僅含說明Writing & Content DevOps & Cloud

AI 產生的概覽

指導團隊使用 fhelp CLI 撰寫、組織並發佈 Fusion 應用程式說明文章、版本資訊與常見問題。

功能: 此技能引導應用程式團隊建立 docs/help 資料夾結構，撰寫 Markdown 說明文章與版本資訊，並產生對應的 JSON 設定檔，用來登錄 slug、標題、應用程式鍵與標籤。它說明如何安裝並驗證 Fusion.Help.Cli dotnet 工具、如何針對 Fusion 環境執行文章、版本資訊與 FAQ 同步命令，以及如何透過 Azure DevOps 或 GitHub Actions 管線自動發佈。內容也涵蓋常見同步與身分驗證錯誤的排解方式，以及先在 ci 測試再發佈至 fprd 等安全限制。
適用情境: 適用於團隊需要為 Fusion 應用程式撰寫或重整說明內容、建立或更新版本資訊、新增 FAQ 項目，或為這些文件設定自動發佈流程的情況。不適用於修改 CLI 或後端原始碼，也與 Fusion Help 無關的一般 Markdown 編輯無關。
執行需求: 需要從 Fusion Public NuGet 來源安裝 Fusion.Help.Cli dotnet 全域工具，並具備 .NET SDK，以及透過 az login 或管線服務主體完成 Azure CLI 身分驗證。發佈需要對目標 Fusion 應用程式鍵具備管理員權限，並能存取 Fusion 環境；選用的 CI/CD 使用需要 Azure DevOps 或 GitHub Actions。此技能附有範本與參考文件，但不含指令碼。

Fusion Help Documentation

Author, structure, and publish help docs (articles, release notes, FAQs) via fhelp CLI.

When to use

Write help article for Fusion app
Create/update release notes
Set up docs folder structure + config
Structure markdown for help system
Publish/sync docs to Fusion environment
Add FAQ entries
Set up CI/CD pipeline to auto-publish

When not to use

Modifying fusion-help-cli source (tooling/fusion-help-cli/)
Changing Fusion.Services.Help backend API
General markdown editing unrelated to Fusion Help
Non-documentation tasks

Required inputs

Collect before creating:

Input	Required	Description
App key	Yes	The Fusion app key (e.g. `my-app`, `resource-allocation-landingpage`). User must be admin for this app.
Content type	Yes	`articles`, `release-notes`, or `faqs`
Docs root path	Yes	Where the team stores their docs (e.g. `docs/help/`)
Target environment	For publish	`ci`, `fqa`, `tr`, or `fprd`

Unknown app key → check app admin:

CI: https://fusion.ci.fusion-dev.net/apps/app-admin
Production: https://fusion.equinor.com/apps/app-admin

Look in "Admins" section — must be listed as admin to publish.

Instructions

1. Set up docs folder structure

Create folder layout:

docs/  help/    articles/                    # Markdown article files      images/                    # Article images (PNG format)    release-notes/               # Markdown release note files      images/                    # Release note images (PNG format)    faqs/                        # Optional: markdown FAQ body overrides    help-articles.json           # Article config    help-release-notes.json      # Release notes config (if using release notes)

docs/  help/    articles/                    # Markdown article files      images/                    # Article images (PNG format)    release-notes/               # Markdown release note files      images/                    # Release note images (PNG format)    faqs/                        # Optional: markdown FAQ body overrides    help-articles.json           # Article config    help-release-notes.json      # Release notes config (if using release notes)

Folder and config names are flexible — must match what you pass to fhelp.

2. Create the article config file

Create help-articles.json (tells CLI which articles to sync):

jsonc

{  "articles": [    {      "slug": "my-app-getting-started",        // Must match the .md filename (without extension)      "title": "Getting Started",               // Display title in Fusion Help      "appKey": "my-app",                       // Your Fusion app key      "sortOrder": 1.0,                         // Controls display order (lower = first)      "summary": "Learn how to get started.",   // Short description shown in article list      "tags": ["getting-started", "onboarding"],// Searchable tags      "relevantApps": []                        // Optional: other app keys where this shows    }  ]}

{  "articles": [    {      "slug": "my-app-getting-started",        // Must match the .md filename (without extension)      "title": "Getting Started",               // Display title in Fusion Help      "appKey": "my-app",                       // Your Fusion app key      "sortOrder": 1.0,                         // Controls display order (lower = first)      "summary": "Learn how to get started.",   // Short description shown in article list      "tags": ["getting-started", "onboarding"],// Searchable tags      "relevantApps": []                        // Optional: other app keys where this shows    }  ]}

Config field reference

Field	Required	Type	Description
`slug`	Yes	string	Unique identifier. Must match a `{slug}.md` file in the articles root folder. Use kebab-case.
`title`	Yes	string	Human-readable title displayed in Fusion Help.
`appKey`	Yes	string	Fusion app key this article belongs to. You must be admin for this app.
`sortOrder`	No	number	Controls display order. Lower numbers appear first. Default varies. Use decimals (1.0, 1.1, 2.0) for flexible ordering.
`summary`	Yes	string	Short description shown in article listings.
`tags`	No	string[]	Searchable tags for categorization.
`relevantApps`	No	string[]	Additional app keys where this article should appear.

3. Write article content

Create markdown files in the articles root folder. The filename (without .md) must match the slug in the config.

Article writing guidelines:

Write for end-users of the Fusion app
Use ##, ### for structure — avoid # (title comes from config)
Place images in images/; reference with ![Alt text](images/my-screenshot.png)
CLI auto-uploads images + rewrites paths to CDN
Images must be PNG (CLI limitation)
One topic per article
Link related articles by title (platform handles deep linking)

Example article (docs/help/articles/my-app-getting-started.md):

markdown

## Overview
This guide walks you through the basics of using My App.
## Prerequisites
Before you begin, make sure you have:- Access to the Fusion portal- The correct role assigned to your user
## Step 1: Navigate to the app
Open Fusion and search for "My App" in the app launcher.
![App launcher](images/app-launcher.png)
## Step 2: Create your first item
Click the **New** button in the toolbar to create your first item.
## Need help?
Contact the team on Teams or check the FAQ section.

## Overview
This guide walks you through the basics of using My App.
## Prerequisites
Before you begin, make sure you have:- Access to the Fusion portal- The correct role assigned to your user
## Step 1: Navigate to the app
Open Fusion and search for "My App" in the app launcher.
![App launcher](images/app-launcher.png)
## Step 2: Create your first item
Click the **New** button in the toolbar to create your first item.
## Need help?
Contact the team on Teams or check the FAQ section.

4. Create the release notes config file (optional)

Create help-release-notes.json if team publishes release notes:

jsonc

{  "releaseNotes": [    {      "slug": "my-app-v2-release",              // Must match the .md filename      "title": "Version 2.0 Release",           // Display title      "appKey": "my-app",                       // Your Fusion app key      "publishedDate": "2026-03-14T00:00:00Z",  // Publication date (ISO 8601)      "tags": ["release", "v2"],                // Searchable tags      "relevantApps": []                        // Optional: other app keys    }  ]}

{  "releaseNotes": [    {      "slug": "my-app-v2-release",              // Must match the .md filename      "title": "Version 2.0 Release",           // Display title      "appKey": "my-app",                       // Your Fusion app key      "publishedDate": "2026-03-14T00:00:00Z",  // Publication date (ISO 8601)      "tags": ["release", "v2"],                // Searchable tags      "relevantApps": []                        // Optional: other app keys    }  ]}

Release notes config field reference

Field	Required	Type	Description
`slug`	Yes	string	Unique identifier. Must match a `{slug}.md` file in the release notes root folder.
`title`	Yes	string	Release note title.
`appKey`	Yes	string	Fusion app key. You must be admin.
`publishedDate`	Yes	ISO 8601 date	When the release was published.
`tags`	No	string[]	Searchable tags.
`relevantApps`	No	string[]	Additional app keys.

Example release note (docs/help/release-notes/my-app-v2-release.md):

markdown

## What's new in Version 2.0
### New dashboard
We've completely redesigned the dashboard with new charts and filtering capabilities.
![New dashboard](images/new-dashboard.png)
### Performance improvements
- Page load times reduced by 40%- Search results now appear in under 1 second
### Bug fixes
- Fixed an issue where filters would reset on navigation- Corrected date formatting in the export feature

## What's new in Version 2.0
### New dashboard
We've completely redesigned the dashboard with new charts and filtering capabilities.
![New dashboard](images/new-dashboard.png)
### Performance improvements
- Page load times reduced by 40%- Search results now appear in under 1 second
### Bug fixes
- Fixed an issue where filters would reset on navigation- Corrected date formatting in the export feature

5. Install and authenticate the CLI

Install from the Fusion Public feed:

powershell

dotnet tool install --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" Fusion.Help.Cli

dotnet tool install --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" Fusion.Help.Cli

Update an existing installation:

powershell

dotnet tool uninstall --global Fusion.Help.Clidotnet tool install --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" Fusion.Help.Cli

dotnet tool uninstall --global Fusion.Help.Clidotnet tool install --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" Fusion.Help.Cli

Authenticate via Azure CLI:

CLI uses DefaultAzureCredentials — picks up az login session automatically.

6. Publish documentation

Sync articles:

Sync release notes:

powershell

fhelp releasenotes sync -f docs/help/help-release-notes.json -r docs/help/release-notes -e ci -v

fhelp releasenotes sync -f docs/help/help-release-notes.json -r docs/help/release-notes -e ci -v

Command flags:

Flag	Description
`-f`, `--file`	Path to the JSON config file
`-r`, `--root`	Path to the folder containing markdown files
`-e`, `--env`	Target environment: `ci`, `fqa`, `tr`, `fprd`
`-t`, `--token`	Override the access token (optional)
`-v`, `--verbose`	Show detailed logging output
`--no-validation`	Skip source system check — use with caution, can overwrite UI-created content

Environment promotion order: ci → fqa → fprd (skip tr unless testing infrastructure).

Test in ci before promoting to fqa then fprd.

7. Set up CI/CD pipeline (recommended)

Automate publishing via Azure DevOps or GitHub Actions.

Azure DevOps pipeline example:

yaml

parameters:  - name: environment    type: string    default: ci    values: [ci, fqa, fprd]  - name: azureSubscription    type: string
steps:  - checkout: self
  - script: |      dotnet tool install --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" Fusion.Help.Cli    displayName: "Install fusion help CLI"
  - task: AzureCLI@2    displayName: "Sync help articles"    inputs:      azureSubscription: ${{ parameters.azureSubscription }}      scriptType: pscore      scriptLocation: inlineScript      inlineScript: |        fhelp article sync `          -f ./docs/help/help-articles.json `          -r ./docs/help/articles `          -e "${{ parameters.environment }}" `          -v
  - task: AzureCLI@2    displayName: "Sync release notes"    inputs:      azureSubscription: ${{ parameters.azureSubscription }}      scriptType: pscore      scriptLocation: inlineScript      inlineScript: |        fhelp releasenotes sync `          -f ./docs/help/help-release-notes.json `          -r ./docs/help/release-notes `          -e "${{ parameters.environment }}" `          -v

parameters:  - name: environment    type: string    default: ci    values: [ci, fqa, fprd]  - name: azureSubscription    type: string
steps:  - checkout: self
  - script: |      dotnet tool install --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" Fusion.Help.Cli    displayName: "Install fusion help CLI"
  - task: AzureCLI@2    displayName: "Sync help articles"    inputs:      azureSubscription: ${{ parameters.azureSubscription }}      scriptType: pscore      scriptLocation: inlineScript      inlineScript: |        fhelp article sync `          -f ./docs/help/help-articles.json `          -r ./docs/help/articles `          -e "${{ parameters.environment }}" `          -v
  - task: AzureCLI@2    displayName: "Sync release notes"    inputs:      azureSubscription: ${{ parameters.azureSubscription }}      scriptType: pscore      scriptLocation: inlineScript      inlineScript: |        fhelp releasenotes sync `          -f ./docs/help/help-release-notes.json `          -r ./docs/help/release-notes `          -e "${{ parameters.environment }}" `          -v

GitHub Actions example:

yaml

name: Sync Help Documentation
on:  push:    branches: [main]    paths: ['docs/help/**']
jobs:  sync-docs:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4
      - name: Setup .NET        uses: actions/setup-dotnet@v4        with:          dotnet-version: '8.0.x'
      - name: Install fusion help CLI        run: |          dotnet tool install --global \            --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" \            Fusion.Help.Cli
      - name: Azure Login        uses: azure/login@v2        with:          client-id: ${{ secrets.AZURE_CLIENT_ID }}          tenant-id: '3aa4a235-b6e2-48d5-9195-7fcf05b459b0'          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
      - name: Sync articles        run: |          fhelp article sync \            -f ./docs/help/help-articles.json \            -r ./docs/help/articles \            -e ci -v

name: Sync Help Documentation
on:  push:    branches: [main]    paths: ['docs/help/**']
jobs:  sync-docs:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4
      - name: Setup .NET        uses: actions/setup-dotnet@v4        with:          dotnet-version: '8.0.x'
      - name: Install fusion help CLI        run: |          dotnet tool install --global \            --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" \            Fusion.Help.Cli
      - name: Azure Login        uses: azure/login@v2        with:          client-id: ${{ secrets.AZURE_CLIENT_ID }}          tenant-id: '3aa4a235-b6e2-48d5-9195-7fcf05b459b0'          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
      - name: Sync articles        run: |          fhelp article sync \            -f ./docs/help/help-articles.json \            -r ./docs/help/articles \            -e ci -v

8. FAQs (supplementary)

FAQs use an Excel-based workflow and require app-level access. This is a temporary solution best suited for scenarios where FAQs span multiple apps.

For most teams, managing FAQs through the Fusion Help Admin UI at https://fusion.equinor.com/apps/fusion-help-admin is simpler.

Expected output

docs/help/ folder with articles, images, and config
Markdown article file(s) with proper content
Valid help-articles.json (+ optional help-release-notes.json)
How to install, auth, and run fhelp
CI/CD pipeline snippet (optional)

Troubleshooting

Problem	Cause	Solution
`DefaultAzureCredential failed to retrieve a token`	Not authenticated	Run `az login`
`403 Forbidden`	Not an admin for the app key	Check admin list at the app admin page, or verify the `appKey` in your config
Article not created (skipped)	No matching `.md` file in root folder	Ensure filename matches slug exactly: `{slug}.md`
Source system mismatch warning	Article was created via UI, CLI won't overwrite	Use `--no-validation` carefully, or use a different slug
Images not uploading	Wrong format	Images must be PNG format

Safety & constraints

Never use --no-validation without understanding — can overwrite UI-created content
Test in ci before publishing to fprd
sourceSystem auto-set to Fusion.Help.Cli; CLI and UI articles have different source systems and won't conflict unless --no-validation is used
Slugs must be globally unique — use app-specific prefix (e.g. my-app-getting-started)
Never commit access tokens — use az login or pipeline service principals

來源與署名

來源：equinor/fusion-skills位於skills/fusion-help-docs提交e8fd6cf

授權條款： MIT

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架

Fusion Help Docs

Fusion Help Documentation

When to use

When not to use

Required inputs

Instructions

1. Set up docs folder structure

2. Create the article config file

Config field reference

3. Write article content

4. Create the release notes config file (optional)

Release notes config field reference

5. Install and authenticate the CLI

6. Publish documentation

7. Set up CI/CD pipeline (recommended)

8. FAQs (supplementary)

Expected output

Troubleshooting

Safety & constraints

來源與署名

更多來自 equinor/fusion-skills 的技能

Fusion Skills

Fusion Skill Authoring

Fusion Issue Authoring

Fusion Rules

Fusion Infra Cli

Fusion Help Integration

更多Writing & Content技能

Doc Coauthoring

Writing Guidelines

Job Post Builder

Write Spec

Draft Content

Brand Voice Enforcement