Docs Assembler - build documentation like Lego

Reuse of interchangeable blocks and fragments of text.
A strategy that mirrors classes and variables in programming.
Streamlines development and simplifies editing on growing or complex systems.

This is an experimental port from a c# server/database application - to a GitHub repo/vscode extension. A concept driven by transformational conversations with a robotics firm - HAL Robotics, so their documentation could be edited as markdown files, stored in their GitHub Pages repo, and compiled into manuals, diagnostic/solution walkthroughs, manufacturer specific guides etc - all based on a policy of edit once - update globally - like with classes and components in code.

GitHub Pages

Modular Documentation Demos:
Publish currently targets GitHub Pages, producing Jekyll Markdown.
After a Publish run a Git Commit and Push for GitHub Pages to make changes live.

Repo:
The sample maps are located in the /tsmaps/ folder and published guides in /docs/.

Hosting a website on GitHub Pages is free for public repos.

Bugs, questions or feedback? - Email us

team@netoftrees.com

After an extension update clear vscode history:

Open the Command Palette: Cmd+Shift+P
Type: Clear Editor History

Quick walkthrough

Using a fork of the HAL Robotics documentation repo, initialised to use maps - HAL.Documentation.maps.
It serves as a good example for simple use cases - as there are only shared variables and steps, no linked maps.

BE AWARE: This is not the current version of HAL Robotics documentation - see below

Maps

The main building block is a map.
It is a json file with a .tsmap extension.
Functions similarly to a class in software.
Maps are built to scale up easily

Switching between Map Editor and Map Json Editor:

Docs Assembler map json editor gif

Switching between Maps Diff and Maps Json Diff:

Docs Assembler diff map json gif

Steps

A map is a section of documentation divided into steps.
Each step links to a markdown file with the step's documentation text.
Markdown file can be shared between multiple steps.
Markdown files are editable with the Visual Studio Code markdown editor.

Docs Assembler steps gif

Maps can reference other maps

A map referenced within another map, appears as a single step.
If a referenced map has exits, other maps or steps will need chained onto those exits.
Validation prevents circular references.

Docs Assembler charts gif

Variables

Variables define reusable markdown text.
Variables that define relative links are adjusted to be always be valid for the published document they are used in.

Docs Assembler variables gif

Variables can reference other variables

A variable's markdown text can reference other variables.
Validation prevents circular references.

Docs Assembler variables nested gif

Compile to docs

On publish, the Docs Assembler reads the maps selected for publish - it validates and assembles all referenced maps, markdown files, expands any variables, copies over referenced assets, and compiles the resuls into markdown or html files to the publish folder in your repo.

Docs Assembler publish gif

Compare published to live

Use the compare view to view changes between published files and the docs folder files.

Docs Assembler compare gif

Move published to live

If the changes are as expected, click-move the published files to the docs folder. If you use GitHub Pages, docs would be the root folder.

Docs Assembler live gif

Built to handle both complexity and scale

At its simplest, a map has a single step and markdown file.
A slightly more complex map would be a single pathway of steps, like a book or manual.
At its most complicated, a map is a decision tree of steps, many pointing to other maps, which in turn point to other maps etc. The expanded result could be enormous, and impossible to buildor maintain without breaking it down into manageable, discrete, reusable, units. Just like we do in code with classes.

Example of published output

netoftrees C# server/database applications gif

Image above

This shows the c# server/database application, where steps are stored in a database.
- It has all the ancillaries expanded.
- When all ancillaries are collapsed the guide shows enough information for an expert to complete the task.
- If a user expands an ancillary, they insert more steps on a topic.
- Ancillaries can be nested - so users can drill down.
- With all possible ancillaries expanded, all the steps for completing a task, as a novice, are laid out.
Reusing maps makes it straight forward to build and maintain guides that a user can tailor to their skill set.

Image below

This shows the editor for the c# server/database application.
- With the referenced maps, including nested ones, used to build the guide shown above.
- Most will be reused in other guides.