placeos / docs Goto Github PK
View Code? Open in Web Editor NEWPlaceOS guides, tutorials and references.
Home Page: https://docs.placeos.com
PlaceOS guides, tutorials and references.
Home Page: https://docs.placeos.com
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.
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:
Auth Articles to be grouped together in a sub-category, suggest category to be called SSO & SAML or similar.
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
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.
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.
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.
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)
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.
Document Kubernetes Deployment Process for:
Azure AKS
GCP
AWS
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
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
https://docs.google.com/document/d/1WJOAMgs8ZppFrIVzlkTWDiV8vgZ_KJf766XSpv9nnzw/edit#
Intro to the platform purpose, high-level concepts and core terminology.
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:
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.
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.
If a check fails such as in #56 (dead link prevents build) this should be visible on the repo/PR
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:
org
, building
and level
zone to run.composer
object in the settings.tsapp
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
building
level take precedence over org
level overridescurrentUser
method in user-state.tsts-client
provides methods to interact with metadata.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.ts-client
API though both can have matching users.Add recommended hardware page from confluence to docs: https://acaprojects.atlassian.net/wiki/spaces/SD/pages/73924609/Recommended+Hardware
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:
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:
simplicity
, which is a basic set of suggested replacements using these rules, andreadability
, 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.
Include links out to existing API Documentation (temporary solution pending OpenAPI)
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.
Add MQTT Documentation: https://docs.google.com/document/d/1gBZD296sF0cZXYyRKrRjn-wi5c408Yg1189S-DV9JgE/edit
Document the features, purpose and use of the PlaceOS Spec Runner tool.
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.
How to add, configure and test a Calendar Driver for
Calendar Driver: https://github.com/PlaceOS/drivers/blob/master/drivers/place/calendar.cr
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.
Migrate Security & Compliance from Public Site: https://place.technology/security
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.
Issue can be expanded as it is investigated, may require splitting if some parts are much more work.
+
to Add Domainplaceos.domain.com
(can be anything to identify the domain, usually the domain itself makes most sense)placeos.domain.com
/login?continue={{url}}
/auth/logout
Backoffice
true
https://placeos.domain.com/backoffice/oauth-resp.html
+
to Add Usertrue
You can now login with the new user on the new domain.
Documentation to step through configuring Staff API and connecting to 365/Google for Use with Calendars & Room Booking
Deployment articles to be grouped in sub-category for deployment.
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.
Put together instructions on configuring Okta for PlaceOS SAML Auth.
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
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.
Wide audience glossary of specific platform terminology like zones, drivers, modules, systems etc.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.