If a check fails such as in #56 (dead link prevents build) this should be visible on the repo/PR

Wide audience glossary of specific platform terminology like zones, drivers, modules, systems etc.

Having a central glossary is both a lot of work to get right, but also probably useful long term. There are some ad-hoc parts where words link to their wiki pages or something, but a unified solution could be good.
Can have some feature where the first instance of a glossary word on a page is a link to the glossary entry. Could be worked in with the solution for #34 or entirely separate

https://www.gartner.com/en/information-technology/glossary

https://docs.google.com/document/d/1I-9YXhYF9Xo3Mf7fYssqckdUcN_J0z215XBgtuisAr0/edit?usp=sharing
This srs ended up including a glossary.
It was worked on bit by bit, probably the best way to build it up.

From place-labs/orthograph-err#8 (comment)

A lot of the current phase of customizing Orthograph-err is in finding & detailing specific exceptions. I foresee future stages involving higher/broader decisions such as consistent use of second person or title case, which are the typical jurisdiction of style guides. Textlint supports rule-presets which could be useful in both of these cases, or at least could be implemented alongside a full style guide as a fallback.

For example, google has a style guide for technical documentation which has a community-implemented textlint-rule-preset
https://github.com/textlint-rule/textlint-rule-preset-google
and
https://developers.google.com/style
—@mghill

• Configure Meraki
• Configure DNA Spaces
• People Finding with Meraki
• Locating users
• Capturing user devices
• Location Services overview

https://docs.google.com/document/d/1WJOAMgs8ZppFrIVzlkTWDiV8vgZ_KJf766XSpv9nnzw/edit#

Document the process for creating unattended auto login, often used for kiosks and av control devices.

Existing documentation can be found at: https://acaprojects.atlassian.net/wiki/spaces/TT/pages/55673351/Endpoint+Auto+Login

Suggest nesting this under user interfaces or similar content related to the configuration and deployment of user interfaces.

There looks to have been a change in some of the actions payload formats that has knocked the proofreader offline. Issue is in the place-labs/orthograph-err#4. Tracking here for impact on this repo.

Pick out what structure and content is relevant from the engine.place.technology site, which needs to be transferred over & how much it needs to be reworked

https://github.com/acaengine/docs

https://engine.place.technology/integrations/location-services/svg-map-creation

Some relevant overview here
Migrate and update documentation which is at a relatively high level for prospective or new clients, particularly non-tech stakeholders.

Notes from first call:

• sales direct to cust and partner
• parntner resoures need collating but are still in progress
• questions from end customers:
• • What is PlaceOS in docs: integration & operation system
• architecture overview & EXAMPLE
• PRIVACY & security - active drectory & ppl tracking
• Video summary for some realy high coverage parts
• roadmap fed from github (opaque to non-techs)

• desk booking
• room booking
• catering
• visitor management
• physical control
• access control

Add AWS Fargate Deployment Docs from Deploy Repo to PlaceOS Documentation Site:
https://github.com/PlaceOS/deploy-aws/blob/modular/README.md
https://github.com/PlaceOS/deploy-aws/blob/nested/README.md

The site build process used for PR preview generation is including ignored content (README files) in pre build checks. This results in preview builds failing when these docs link to each other as the links to not exist in the output.

Example visible in #52.

Document the features, purpose and use of the PlaceOS Spec Runner tool.

Put together instructions on configuring Okta for PlaceOS SAML Auth.

Given this content defines the URL structure and in turn becomes part of the user interface for consumption, it is worthwhile defining a hierarchy and some guidelines for this to ensure consistency.

Opening this issue to capture and provide a reference for decisions that space.

The inputs to work with are:

• folders become URL path prefixes
• document names form the final component of the URL path (unless overridden in frontmatter)
• headings within documents become anchors (slugged unless explicitly defined)

For example
_{file: an/example/path/doc.md}

This is some text, likely more above.

# Foo
An interesting point of interest.

The 'Foo' section of the doc below could be linked directly as https://docs.placeos.com/an/example/path/doc#foo

Once a doc is published, it is likely that it and sections within it may be linked externally. We can create different reference versions if there is a need for large scale changes in the future, however as a general principle it would be good to ensure that any linkable items become immutable references to help prevent broken references.

Auth Articles to be grouped together in a sub-category, suggest category to be called SSO & SAML or similar.

When a PR is submitted from an external fork, the proofread check fails due to access issues.

Example failed run: https://github.com/PlaceOS/docs/pull/47/checks?check_run_id=1731506587.

• Migrate across required (preexisting) images and assets to embed into docs,
• Source any glaringly missing assets (if any)
• Find/implement solutions for:
  • Flowcharts inline with text like this
  • Feature demos, either stills, animated captures, or "live" simulations

Issue can be expanded as it is investigated, may require splitting if some parts are much more work.

1. desk booking overview
2. configure desk booking (backoffice)
   2.1 zones
   2.2 meta-data
3. desk management via concierge

A recent change to behaviour was made so that site publishing takes place from this repository directly, pulling in placeos/docs-site as a dependency. This appears to have impacted publishing of preview builds as the Docusaurus build cache now appears within node_modules/placeos-docs-site/, which in turn is cached by Vercel.

This is causing stale content to be published, and builds to fail.

Add recommended hardware page from confluence to docs: https://acaprojects.atlassian.net/wiki/spaces/SD/pages/73924609/Recommended+Hardware

Extending from #25 (comment).

Company and product names / model identifiers present an issue for accurate linting. In many cases these are intentionally misspelled words. Using directly exceptions may introduce an undesired side effect of also missing actual mistakes.

There's a few approaches here - issue it open for discussion.

Include links out to existing API Documentation (temporary solution pending OpenAPI)

• PlaceOS Core API
• Staff API

Migrate Security & Compliance from Public Site: https://place.technology/security

https://engine.place.technology/security

Some relevant overview here
There's a lot here, but very scattered. Some outdated Engine stuff, some needs a lot of work. Needs adaptation to be suitable for tech & non-tech audiences (most parts only have 1 or the other currently)

Notes from first call:

• External partners will need, for a fresh install
• see a template staff app running
• list of steps to instantiate zones/systems hierarchy
• list of all available valid metadata fields & MEANING/USE
• Syntax for metadata & building/zone standards
• specific config points/variables for common customisations
• So then how do we connect a frontent to a configured backend (local dev or external server) - auth, proxy etc.
• WALKTHROUGH/Worked Example!!
• Integrating staffapi with microsoft graph/google (there is a steve doc somewhere)
• some docs for ACA Engine, mostly still relevant
• spinup a partner environ & have a go connecting it to graph -> IF there is a walkthrough try following it
• there is an APIary doc for staffapi - steve and will. Newer and better examples can be put in.
• sidecar (?) doc explaining API calls for a given/common flow (USE CASE)
• High/medium level stuff about i.e. how to setup sensors & peripheral stuff (vergesense, poc) custom placeOS logic, per customer but the overall at an abstract level "what is required by placeOS OF a third party sensor"
• deployment doco - k8s oriented deployment (prod & staging environ)
• k8s doco mostly written by deloitte in placelabs/k8s.... which are pretty good

• Templates require an org, building and level zone to run.
• Authentication is initialised from composer object in the settings.ts
• The base settings.ts file contains all the required settings for setting up the application
• The base settings file is overridden at the application level by their settings.ts in the environment folder. e.g. Workplace Override
• All the settings under the app key can be overridden by metadata at the org and building zone level. The overriding metadata should have the name with the format <app_name>_app e.g. workplace_app
• Overrides at the building level take precedence over org level overrides
• Logged in User details are automatically loaded and can be retrieved using the currentUser method in user-state.ts
• User preferences can be setup through the creation of associated metadata.
  • ts-client provides methods to interact with metadata.
  • To retrieve showMetadata(user.id, { name: 'preferences' }) and to update updateMetadata(user.id, { name: 'preferences', description: '', details: { theme: 'dark' } });
• ts-client offers methods for creating zones, metadata and users if automated scripts are needed.
• Each of the respective Staff API endpoints have methods to make requests to them.
  • Bookings API Methods
  • Calendar API Methods
  • Events API Methods
  • People API Methods
  • Guest API Methods
• The people endpoints retrieves user data from the clients user directory (ADFS, LDAP etc.).
  • These "users" are different from the user data that can be retrieved by the ts-client API though both can have matching users.
  • Users that login via SSO get created as a user in the PlaceOS database with the details from the clients user directory.

Wide audience glossary of specific platform terminology like zones, drivers, modules, systems etc.

Rather than defaulting to inline HTML <abbr> tags, it would be nice to define a common syntax for usage within doc content, which the parser will then transform to these.

A good option for this looks to be via remark-abbr.

This will also allow these to be checked via the the linter, rather than needing to add exception, or a blanket ignore rule.

Originally from #29 (comment)

Add a domain to PlaceOS

1. Log in to Backoffice on the domain created during deployment. eg. https://1.2.3.4.xip.io/backoffice/
2. Domains tab (left menu) + to Add Domain

• Name: placeos.domain.com (can be anything to identify the domain, usually the domain itself makes most sense)
• Domain: placeos.domain.com
• Login URL: /login?continue={{url}}
• Logout URL: /auth/logout

3. Select the newly created Domain -> Applications -> New Application

• Name: Backoffice
• Scopes: leave blank
• Skip Authorization: true
• Login URL: https://placeos.domain.com/backoffice/oauth-resp.html

4. Users tab + to Add User

• Domain: Select the domain created in step 2
• First and Last name are required
• Email: This will be the username (can be any valid email string)
• System Admin: true

You can now login with the new user on the new domain.

Rousseau is currently used as part of the automated proofreading, however most checks are disabled due to duplication with other tools. It does not appear to be actively maintained and has a number of security advisories associated with upstream deps which would be good to either resolve, or prevent from pollution tooling used here.

The currently enabled checks are:

1. simplicity, which is a basic set of suggested replacements using these rules, and
2. readability, which implements an automated readability index.

@mghill are either of these providing useful feedback? If not, a simple fix is to drop its usage. If yes, can look at patching upstream, or re-implementing these as standalone textlint rules.

Some relevant overview here
These are very scant, some for Engine, a lot outdated. Need some for dev/partners, and some for users.

Notes from first call:

• deploying & setup environ
• structure of application
• hooking up live & dev servers
• No Docs For This
• auth process, API, templates
• SSO/local login for dev
• angular related info
• examples & case studies
• Some Docs But Very Vague

Intro to the platform purpose, high-level concepts and core terminology.

Several (placeholder?) branches started by @stakach require curation, editing and merging. PRs for them have been closed until this review takes place, at which point I will open new PRs as each branch is ready.

How to add, configure and test a Calendar Driver for

1. MS Graph (office365)
2. Google Workspace API

Calendar Driver: https://github.com/PlaceOS/drivers/blob/master/drivers/place/calendar.cr

High-level info in https://github.com/PlaceOS/drivers/tree/master/docs. Needs a neaten up and expansion to help explain to tools available as part of the driver framework.

https://docs.google.com/document/d/12lCTbqLP2QPg1Gbey9GWLMyDXLFJ6DyolPy65uBnW_c/edit#heading=h.snxcqt1425dd

Link titles should not flag spelling errors for terms contained with the link itself.

This will avoid having to designate as idiomatic terms, or specify additional markup for clearly correct references.

Deployment articles to be grouped in sub-category for deployment.

Document Kubernetes Deployment Process for:
Azure AKS
GCP
AWS

https://github.com/place-labs/k8s-helm

Documentation to step through configuring Staff API and connecting to 365/Google for Use with Calendars & Room Booking

Generate a logical services interaction/integration map to clearly convey how various services interact i.e. staff api with regards to bookings then connected into additional driver data such as floorsense.

This seems to be a sticking point for partners developing against and/or trying to understand the logical inner workings of the various aspects of the platform.

Original doc has screenshots as part of walkthrough but these are of the old backoffice and need replacing. Main body of text has been updated without images for now

Referring to this commit, the linter finds issue with the imports at the top (which can presumably be wrapped in a tag of some sort?), and the Tabs declaration on line 21 (which is only slightly more complex than an open/close tag) . The closing tags etc have no issues.

Add MQTT Documentation: https://docs.google.com/document/d/1gBZD296sF0cZXYyRKrRjn-wi5c408Yg1189S-DV9JgE/edit