Merge pull request #433 from OpenFn/joe-feedback

Various minor docs tweaks and sidebar restructure (aka feedback from Joe)

Author: aleksa-krolls

docs/build-for-developers/cli-intro.md

@@ -7,37 +7,37 @@ slug: /cli
 #### Build and test your automated workflows and integrations via the command line.
 
 The OpenFn CLI is a developer tool to help you build, test, and manage your
-workflows and integration with OpenFn directly from the command line. It’s
-simple to install, works on macOS, Windows, and Linux, and offers a range of
-functionality to enhance your developer experience with OpenFn. You can use the
-OpenFn CLI to:
+workflows directly from the command line. It’s simple to install, works on
+macOS, Windows, and Linux, and offers a range of functionality to enhance your
+developer experience with OpenFn. You can use the OpenFn CLI to:
 
 - Securely run OpenFn steps and workflows
 - Troubleshoot and debug OpenFn steps
-- Deployment of workflows to OpenFn
+- Access adaptor documentation
+- Deploy workflows to OpenFn
 
 ---
 
 ### Before you start
 
-Before you begin with the @openfn/cli, make sure to follow these simple steps:
+Before you begin with the @openfn/cli, make sure to setup some key tooling:
 
 1. **Code Editor:** Ensure you have a code editor installed on your machine. You
    can use popular editors like [VS Code](https://code.visualstudio.com/) or
    [Sublime](https://www.sublimetext.com/).
-2. **Node.js Installation:** Install Node.js (version 18 or later): - For Linux,
-   Windows, or macOS, use a version manager like
-   [nvm](https://github.com/nvm-sh/nvm) or
-   [asdf](https://asdf-vm.com/guide/getting-started.html). -
-   [Install Node.js](https://kinsta.com/blog/how-to-install-node-js/) by
-   following this guide.
-3. **Understand OpenFn Basics:** Have a basic understanding of OpenFn,
-   particularly steps and adaptors. Check out the [Intro section](/documentation)
-   on this site.
+2. **Node.js:** Install Node.js (version 18 or later). For Linux, Windows, or
+   macOS, use a version manager like [nvm](https://github.com/nvm-sh/nvm) or
+   [asdf](https://asdf-vm.com/guide/getting-started.html). Or
+   [install Node.js directly](https://kinsta.com/blog/how-to-install-node-js/)
+   by following this guide.
+
+You should also **understand OpenFn Basic concepts**, particularly steps and
+adaptors. Check out the [Intro section](/documentation) on this site to get
+caught up.
 
 ---
 
-### Install the OpenFn CLI
+### Install the CLI
 
 To download the latest version of
 [@openfn/cli](https://www.npmjs.com/package/@openfn/cli), on the command line,
@@ -47,7 +47,7 @@ run the following command.
 npm install -g @openfn/cli
 ```
 
-**Make sure everything works by running the built-in test job**
+Make sure everything works by running the built-in test workflow:
 
 ```bash
 openfn test
@@ -127,7 +127,7 @@ openfn help
 
 ---
 
-### Update the OpenFn CLI
+### Updating the CLI
 
 To install a new version straight on top of your current installation, run the
 following command.
@@ -138,7 +138,7 @@ npm install -g @openfn/cli
 
 ---
 
-### Troubleshoot Installation
+### Troubleshooting
 
 If you encounter installation issues, try uninstalling the current version first
 and then re-installing.

docs/build-for-developers/cli-usage.md

@@ -4,10 +4,21 @@ sidebar_label: Basic usage
 slug: /cli-usage
 ---
 
-#### Execute a job, run a workflow, adjust logging, maintain adaptors, and save the state.
+This page shows common usage examples for the CLI.
 
-You're probably here to run steps (expressions) or workflows, which the CLI
-makes easy. Keep reading for an outline of the basic usage scenarios of the CLI.
+Execute a job, run a workflow, adjust logging, maintain adaptors, and save the state.
+
+---
+
+### Get help
+
+```bash
+openfn --help
+```
+
+```bash
+openfn deploy --help
+```
 
 ---
 
@@ -17,35 +28,39 @@ To run a single job, you must explicitly specify which adaptor to use. You can
 find the list of publicly available [adaptors here](/adaptors). See examples
 below.
 
-> Adaptors are auto-installed if the specified version is not detected.
+Adaptors are automatically installed if the specified version is not detected.
 
-**Use a shorthand (e.g., `http`):**
+**Run a job with the http adaptor:**
 
 ```bash
 openfn path/to/job.js -a http
 ```
 
-**Use the full package name (e.g., `@openfn/language-http`):**
+**Use a specific adaptor version:**
 
 ```bash
-openfn path/to/job.js -a @openfn/language-http
+openfn path/to/job.js -a http@2.0.0
 ```
 
-**Add a specific version:**
+**Pass a path to a locally installed adaptor:**
 
 ```bash
-openfn path/to/job.js -a http@2.0.0
+openfn path/to/job.js -a http=/repo/openfn/adaptors/my-http-build
 ```
 
-**Pass a path to a locally installed adaptor:**
+**Use the build in the adaptors monoreo:**
 
 ```bash
-openfn path/to/job.js -a http=/repo/openfn/adaptors/my-http-build
+openfn path/to/job.js -ma http
 ```
 
+Set a path to the monorepo with the env var OPENFN_REPO_DIR (eg, `OPENFN_REPO_DIR=~/openfn/repo openfn job.js -ma http`).
+
+Remember to rebuild the adaptor before using it!
+
 ---
 
-### Write resulting state to disk
+### Handle output state
 
 After the job finishes, the CLI writes the resulting state to disk. By default,
 it creates an `output.json` next to the job file.
@@ -56,8 +71,6 @@ it creates an `output.json` next to the job file.
 openfn path/to/job.js -a adaptor-name -o path/to/output.json -s path/to/state.json
 ```
 
-### Return resulting state through stdout
-
 **Use `-O` to return the output through stdout:**
 
 ```bash
@@ -153,3 +166,23 @@ openfn path/to/workflow.json -o tmp/output.json
 
 Check out this detailed [tutorial](cli-walkthrough#7-running-workflows) on
 running workflows via the CLI.
+
+---
+
+### Load adaptor documentation
+
+The CLI can list adaptor documentation in the terminal. Note that it has to download
+the adaptor to the repo (if it's not already there), which can take a moment.
+
+**Print a list of adaptor functions**
+
+```bash
+openfn docs http
+```
+
+
+**Show docs for a specific function**
+
+```bash
+openfn docs http post
+```

docs/get-help/support.md

@@ -1,6 +1,6 @@
 ---
 title: Support for OpenFn Implementations
-sidebar_label: Support
+sidebar_label: Get Help
 ---
 
 ## Ask the Community! 

docs/get-started/glossary.md

@@ -1,21 +1,20 @@
 ---
-sidebar_label: Glossary for Integration
+sidebar_label: Glossary
 title: A glossary for data integration
 ---
 
-Now that we've got a basic understanding of what an integration is, it's
-important to establish some of the foundational concepts we need to press
-forward. This doesn't mean you can't use OpenFn if you don't know what any of
-these words mean prior to reading our documentation, but it does mean that some
-of the most important tasks along the OpenFn journey will assume at least a
-basic understanding of each of these terms. In some cases, we also link to
-further reading if you want a better understanding of some part of your data
-integration picture.
+This glossary establishes some of the foundational concepts and terms used while
+talking about data integration and workflow automation.
 
-Note: This glossary is meant to be OpenFn-agnostic. The rest of the docs and
+This doesn't mean you can't use OpenFn if you don't know what any of these words
+mean prior to reading our documentation - but it does mean that some of the most
+important tasks along the OpenFn journey will assume at least a basic
+understanding of each of these terms.
+
+This glossary is meant to be OpenFn-agnostic. The rest of the docs and
 [Key Concepts page](/documentation/get-started/terminology) help you to get a
-picture of the parts of OpenFn, what we call them, and why, but this glossary is
-really meant as a prerequisite to all those other things to aid users with no
+picture of the parts of OpenFn, what we call them, and why - but this glossary
+is really meant as a prerequisite to all those other things to aid users with no
 experience in this area.
 
 :::tip Something missing?
@@ -133,8 +132,8 @@ data to a destination system.
 
 ## Webhook
 
-A [webhook](/documentation/build/triggers#webhook-event-triggers) (also
-called a web callback or HTTP push API — thanks
+A [webhook](/documentation/build/triggers#webhook-event-triggers) (also called a
+web callback or HTTP push API — thanks
 [SendGrid](https://sendgrid.com/blog/whats-webhook/)!) is a feature of an
 application that allows <i>pushing</i>. It's often configured to notify some
 external URL when an event occurs. A system administrator might create a

docs/get-started/home.md

@@ -1,27 +1,16 @@
 ---
-title: About
+title: What is Openfn?
 id: home
 sidebar_label: What is OpenFn?
 slug: /
 ---
 
-:::tip Automation, integration, & interoperability
-
-OpenFn is open source software that makes it easier for governments and NGOs to
-_connect_ the different technologies they use, automate critical business
-processes, and scale their interventions. OpenFn enables automation,
-integration, and data interoperability for the worlds most impactful
-organizations.
-
-:::
-
-## What is OpenFn?
-
 **OpenFn is the leading
 [Digital Public Good](https://digitalpublicgoods.net/digital-public-goods/) for
-workflow automation**–a platform that's been used by 70+ NGOs and government
-ministries to automate and integrate critical business processes and information
-systems.
+workflow automation**.
+
+It is a platform that's been used by 70+ NGOs and government ministries to
+automate and integrate critical business processes and information systems.
 
 **Connect any app** with OpenFn's library of open-source [Adaptors](/adaptors/)
 (i.e., connectors). From last-mile services to national-level reporting, OpenFn
@@ -30,15 +19,25 @@ interoperability at all levels.
 
 OpenFn can be deployed locally or on the secure
 [cloud-hosted platform](https://openfn.org/pricing). See the
-[Deploy docs](/documentation/deploy/options) for more on deployment options and
-requirements.
+[Deployment docs](/documentation/deploy/options) for more on deployment options
+and requirements.
 
 To support implementers, OpenFn has an online
 [community](https://community.openfn.org), documentation, and
 [support](mailto://[email protected]). Contact
 [[email protected]](mailto://[email protected]) to learn about
 OpenFn implementation partners and the OpenFn Partner Program.
 
+:::tip Automation, integration, & interoperability
+
+OpenFn is open source software that makes it easier for governments and NGOs to
+_connect_ the different technologies they use, automate critical business
+processes, and scale their interventions. OpenFn enables automation,
+integration, and data interoperability for the worlds most impactful
+organizations.
+
+:::
+
 ## Our products
 
 OpenFn has a suite of products, which are all fully interoperable. This gives
@@ -52,12 +51,15 @@ open-source `OpenFn Integration Toolkit`, which is a **Digital Public Good** (a
 
 The core OpenFn products include:
 
-- **[OpenFn/lightning](https://github.com/OpenFn/lightning): the "v2"** open
-  source platform - current version
-- OpenFn/platform v1: replaced by the v2; soon to be sunsetted in 2025
+- **[OpenFn/lightning](https://github.com/OpenFn/lightning)**: our open source
+  data integration & workflow automation platform. This is the "v2" version
+  currently in use.
+- OpenFn/platform: the first version of our platform. Replaced by v2 and due to
+  be sunsetted in 2025
 - [**OpenFn/adaptors**](https://github.com/OpenFn/adaptors): source code for
   adaptors
-- [**OpenFn/kit**](https://github.com/OpenFn/kit): developer tooling & CLI
+- [**OpenFn/kit**](https://github.com/OpenFn/kit): CLI, developer tools and
+  Javascript runtimes
 - [**OpenFn/docs**](https://github.com/OpenFn/docs): documentation & source for
   docs.openfn.org
 
@@ -66,15 +68,15 @@ See all products and code at [Github.com/OpenFn](https://github.com/OpenFn).
 ### OpenFn v2: Lightning ⚡
 
 When you hear "OpenFn", think
-[OpenFn/lightning](https://github.com/OpenFn/lightning/)--**the OpenFn "v2"**.
-It is a _fully open source_ workflow automation web application which can be
-deployed and run anywhere. It is designed for governments and NGOs who want
-state-of-the-art workflow automation and data integration/interoperability
-capabilities with fully-fledged user management and auditing capabilities
-through a managed _or_ entirely self-hosted platform.
+[OpenFn/lightning](https://github.com/OpenFn/lightning/). v2 is a _fully open
+source_ workflow automation web application which can be deployed and run
+anywhere. It is designed for governments and NGOs who want state-of-the-art
+workflow automation and data integration/interoperability capabilities with
+fully-fledged user management and auditing capabilities through a managed _or_
+entirely self-hosted platform.
 
-The v2 leverages the same tried-and-trusted core technology as the OpenFn v1 and
-comes with an improved, visual interface for building integrations.
+Version 2 leverages the same tried-and-trusted core technology as the OpenFn v1
+and comes with an improved, visual interface for building integrations.
 
 ![OpenFn Workflow Canvas](/img/case_referral_workflow.png)
 
@@ -83,7 +85,7 @@ comes with an improved, visual interface for building integrations.
 on Youtube to watch videos that will help you get started quickly, or check out
 the other docs pages on the site.
 
-:::info OpenFn v2 replaces the v1
+:::info OpenFn v2 replaces v1
 
 OpenFn v2 is available to any new users. All organizations currently using the
 legacy OpenFn v1 platform will be migrated to OpenFn v2 by the end of 2024.

docs/get-started/standards.md

@@ -3,7 +3,7 @@ sidebar_label: Standards
 title: Standards & OpenFn
 ---
 
-OpenFn’s software follows global standards for open source software and for workflow engine solutions. Read on to learn how OpenFn complies with specific standards.
+OpenFn follows global standards for open source software and for workflow engine solutions. Read on to learn how OpenFn complies with specific standards.
 
 
 ## Digital Public Good

docs/get-started/terminology.md

@@ -7,7 +7,7 @@ find some OpenFn-specific terminology that's important to understand. This page
 is your reference guide—a glossary of the most important _OpenFn-specific_ words
 and what they mean.
 
-:::note Something missing?
+:::tip Something missing?
 
 If you've come across a word, phrase, or concept that you think is missing from
 this page, open an issue on [OpenFn/docs](https://github.com/OpenFn/docs),

docs/get-started/try-out.md

@@ -49,8 +49,8 @@ without limits. See our Github repo for developer docs:
 
 :::info Questions?
 
-Don't forget to check out the new docs on specific featurs (see menu sidebar),
-browse the [main docs page](./home.md), or post questions on
-[Community](https://community.openfn.org) if you have any questions.
+Check out these docs for more details on specific features (see menu sidebar),
+browse the [main docs page](./home.md), or post your questions on
+[Community](https://community.openfn.org).
 
 :::