Nature Preceded Machines

    self-help

    0.3.2 • Public • Published

    self-help

    Interactive Q&A Guides for Web and the Command Line

    NPM version NPM downloads Build Status Maintainability

    Table of Contents

    🌩 Installation

    npm install --global self-help
    

    🕹 Usage

    Interactive CLI

    Navigate a Self-Help Document from the Command Line:

    self-help interactive --source ./path/to/help-document.js
    

    Example

    screenshot

    Generate Markdown

    Generate Markdown from a Self-Help Document:

    self-help markdown --source ./path/to/help-document.js
    

    Markdown is written to stdout for you to pipe into other Command Line Programs or write to a file.

    Example

    The self-help RxJS Operator Decision Tree Example exported as Markdown.

    👩🏽‍💻 Writing Documents

    A Help Document is a JavaScript Module exporting a getHelpDocument method of type GetHelpDocument.

    type GetHelpDocument = () => Node | Promise<Node>;

    It returns a Nested Hierarchy of Node Objects.

    type Node = Leaf | Branch | AsyncBranch;

    Which form the Decision Tree a User will navigate.

    export const getHelpDocument = (): Node => ({
      label: "Welcome to Milk and Cookies, how can we help?",
      children: [
        {
          label: `I'm Thirsty, and`,
          children: () => http.get("/milks-walkthrough.json")
        },
        {
          label: `I'm Hungry, and`,
          children: [
            {
              label: "I love Cookies, so",
              children: () => http.get("/cookies-walkthrough.json")
            },
            {
              label: `Cookies aren't my thing`,
              value: fs.readFileSync("/GET-OUT.md", "utf8")
            }
          ]
        }
      ]
    });

    Node Types

    Branch

    A Branch presents multiple options to choose from in the form of its children Array. Children can be a combination of other Branch, AsyncBranch or Leaf Nodes.

    {
      label: 'I just cloned the project, and',
      children: [...]
    }

    AsyncBranch

    An AsyncBranch is the same as a Branch except its children property is a Function which returns a Promise.

    This mechanism allows Help Documents to be combined and linked together, use it to compose higher-level guides which pull together other Help Documents hosted online or break down a large Help Document into smaller files that can be lazily-loaded at runtime.

    {
      label: 'I just cloned the project, and',
      children: () => Promise.resolve([])
    }

    Leaf

    A Leaf represents the answer the User has been looking for as they have been navigating a given Help Document. The value can be any String, but is normally the contents of a Markdown Document which explains the answer to the User.

    {
      label: 'I want to install dependencies',
      value: fs.readFileSync('/installation.md', 'utf8')
    }

    🙋🏿‍♂️ Getting Help

    Get help with issues by creating a Bug Report or discuss ideas by opening a Feature Request.

    👀 Other Projects

    If you find my Open Source projects useful, please share them ❤️

    🤓 Author

    I'm Jamie Mason from Leeds in England, I began Web Design and Development in 1999 and have been Contracting and offering Consultancy as Fold Left Ltd since 2012. Who I've worked with includes Sky Sports, Sky Bet, Sky Poker, The Premier League, William Hill, Shell, Betfair, and Football Clubs including Leeds United, Spurs, West Ham, Arsenal, and more.

    Follow JamieMason on GitHub      Follow fold_left on Twitter

    Keywords

    none

    Install

    npm i self-help

    DownloadsWeekly Downloads

    0

    Version

    0.3.2

    License

    MIT

    Unpacked Size

    74.7 kB

    Total Files

    34

    Last publish

    Collaborators

    • fold_left