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 cont

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: 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): 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 ): 4. Create the release notes config file (optional) Create help release notes.json if team publishes release notes: 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 ): 5. Install and authenticate the CLI Install from the Fusion Public feed: Update an existing installation: Authenticate via Azure CLI: CLI uses DefaultAzureCredentials — picks up az login session automatically. 6. Publish documentation Sync articles: Sync release notes: 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: GitHub Actions example: 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

fusion-help-docs