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/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 git 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.
Bugs, questions or feedback?
team@netoftrees.com
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
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.
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.
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.
Variables can reference other variables
- A variable's markdown text can reference other variables.
- Validation prevents circular references.
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.
Compare published to live
Use the compare view to view changes between published files and the docs folder files.
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.
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
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.
Upcoming
- Port from database version
- projects
- publish for ancillaries and referenced maps
- search
- shape
- spread
- Docker database + SPA viewer
- Example repository
- Tutorials and help files
- Light theme
Notes
- Encapsulation - Wrapping a segment of the documentation within a single map.
- Inheritance - Deriving a new map from an existing map (parent).
- Polymorphism - Grouping maps as members of a common superclass (e.g., tiger, lion => cats).
- Abstraction - Hiding complex documentation details within a map and exposing that map's interface to other maps as a single step.
- Composition - Composing a map of one or more other maps.
Releases
- 0.2.43
- Map folders
- Intellisense, diagnostics and TextMate grammars for steps and variables
- Publish listed maps
- Moving or copying map folder corrects relative urls
Links
team@netoftrees.com
www.netoftrees.com
x.com/docsassembler
documentation:
docs.hal-robotics.com
documentation repo:
github.com/HALRobotics/HAL.Documentation
website:
hal-robotics.com
