triggermesh / docs Goto Github PK

As a developer, I would like to see detailed templates/rules for creating issues and pull requests. As a member of the TriggerMesh application, I would also like to see these guidelines in place to make open source contributions easier.

Expected

• create or template
• create issue template
• provide guidelines for each

As a user, I would like to see the documentation theming to be the same as the Triggermesh theming.

• same fonts
• same colors
• Triggermesh Icon

This will require us to create a css file and add styles to override the default. According to https://www.mkdocs.org/user-guide/styling-your-docs/

Add OCI Metrics Source documentation and update/verify the Oracle Cloud target

https://docs.triggermesh.io/tm/install/

Create a template for sources.

desc

Add docs for Jira Target

https://docs.triggermesh.io/

https://github.com/triggermesh/docs

For technical documentation, have been taught to use the 3rd person in order to remove the perception of bias and also remove a sense of familiarity.

Originally posted by @cab105 in #29

We should modify all pages that use the 2nd person, and remember to follow this rule in the future.

The current getting started guide https://docs.triggermesh.io/guides/gettingstarted/ doesn't have images that match the current interface.

Additionally, The Getting Started Guide should be more explicit then what is currently there. With explanations of sources, bridges, and targets as well as the list of supported services.

The target docs for confluent, googlesheets, and tekton were originally migrated over from the developer documentation, but could use some love by integrating it more into the UI/frontend.

#115

Currently, if I go to this page, (Guides/Bridge/EveryBridge), I see links for source, broker, and trigger.

If I try to click on broker or trigger I am taken to this link https://knative.dev/docs/eventing/broker-trigger/ which shows a 404 page.

Currently, my terminal shows a warning for incorrect links .

Support for retrieving metrics and logs from CloudWatch has recently been added to the source, but would still need some documented love.

Add docs for Confluent Target

Add user facing documentation on setting up the target and provide expectation of the event types as requested by #45.

We need a guide to setup the eventbridge target docs with snapshots from our UI and the AWS UI.

Maybe also a screencast that we can put on youtube

parent task: #45

Make sure the source docs follows the new template

The bullet points should be changed from * to -

Add targets documentation

• What they are
• How to consume them, what automatic translations are supported

Currently there are none

The datadog target was recently updated to use their native API instead of forwarding events through dogstatsd. As a result, the event type and payload has been altered to more accurately reflect what is expected by the Datadog API, however our docs have not been updated to keep in sync.

Apparently the twilio target now needs a specific event type.

It used to be any type but with a specific paylod: https://docs.triggermesh.io/targets/twilio/#event-types

As a user, I would like all of the docs to have the same look and feel. Currently, depending on which dev created the docs, docs are not consistent. This can be difficult for users to know exactly where they can find the info they need.

We have created Target Templates and Examples. We will need all existing Targets to follow this style. You do not need to change screenshots of images, this is only to fix the formatting of text and location of text.

For example, we want an unordered list of the Prerequisites. If there is any test linking to what that prerequisite does or needs, we will need a separate section for that text.

Example:

Prerequisites
- AWS ARN
- AWS Credential

AWS ARN
 This explains the foo bar baz biz

If you see spelling mistakes or grammar mistakes you may fix them in this issue.
If you would like to change the verbiage to something that makes more sense - go for it :)

ToDo

• go to templates/target/targetExample.md change Prerequisites to Prerequisite(s)
• go to templates/target/targetTemplate.md change Prerequisites to Prerequisite(s)
• go through all of the targets in the folder targets and change the format to the template

Update the sources/targets index to reflect all sources and targets. In addition, break up the single AWS target to reflect the different AWS offerings.

There seems to be a nice mkdocs theme with material design:

https://squidfunk.github.io/mkdocs-material/creating-your-site/

It would be interesting to see if this can be used to make our doc website more professional looking.

The knative website is moving to it: https://julz.github.io/docs/dev/

Add the HTTPSource docs

Currently, we have GitLab spelled as Gitlab. Also in the Targets tab, we have Elasticsearch spelled as Elasticsarch

I think this is a good opportunity to go through all of the Services, Targets, etc to make sure that we have all of the company's names spelled correctly and using the correct capitalization.

List of Targets and Services
AWS (Lambda, Kinesis, EventBridge, CodeCommit, SQS, SNS, DynamoDB)
GitHub
GitLab
Datadog
SendGrid
Elasticsearch
Hasura
Oracle
Slack
Splunk
Tekton
Zendesk
Twilio
Azure
OCIMetrics - Oracle Cloud Infrastructure Metrics
Salesforce

Clean up the target documentation to illustrate how to create the target from the UI, and fix a typo in the Slack source.

Add information on Bridges

• What they are
• How to create your own Bridge

As a user, I would like all of the docs to have the same look and feel. Currently, depending on which dev created the docs, docs are not consistent. This can be difficult for users to know exactly where they can find the info they need.

We have created Source Templates and Examples. We will need all existing Sources to follow this style. You do not need to change screenshots of images, this is only to fix the formatting of text and location of text.

For example, we want an unordered list of the Prerequisites. If there is any test linking to what that prerequisite does or needs, we will need a separate section for that text.

Example:

Prerequisites
- AWS ARN
- AWS Credential

AWS ARN
 This explains the foo bar baz biz

If you see spelling mistakes or grammar mistakes you may fix them in this issue.
If you would like to change verbiage to something that makes more sense - go for it :)

ToDo

• go to templates/source/sourceExample.md change Prerequisites to Prerequisite(s)
• go to templates/source/sourceTemplate.md change Prerequisites to Prerequisite(s)
• go through all of the sources in the folder sources and change the format to the template

I tried to install mkdocs based on the ReadMe. What I found was since I had python version 3 installed, the pip command did not work. It was pip3.

macOS Catalina v 10.15.4 using Google Chrome V. 81.0.4044.138

I also tried with another account on Safari V. 13.1

As a user, I would like to use the search bar to easily find information in the documentation.

Currently, if I type in a term to search the documentation, I see that a "?" appears in the URL, but nothing happens.

https://www.loom.com/share/20886128838a424f8ba5a76c112c1885

Expected -

May have to read the MKDocs to see if we need to add any logic.

Currently, the screenshots provided in the documentation are not up-to-date with the current design.

You may need to update directions based on the new screenshots.

Docs for HTTP Target are missing.

Create Salesforce Target Docs

Maybe there should be a rules pages that goes under templates.

Rules:
Use of - for bullets
Capital letter for TriggerMesh known elements like Bridges, Sources, Targets, use TriggerMesh and not Triggermesh.
Use 1. instead of 1. 2. 3. for lists.

Create a template for targets and show example.

Originally posted by @cab105 in #29

According to MLA, all titles should follow some capitalization rules: https://style.mla.org/capitalization-of-titles/

An example of page using that style: https://style.mla.org/plagiarism-and-academic-dishonesty/

@cab105 mentioned we should stick to that style in doc pages, so we should update existing ones and remember to follow those rules in the future.

Sources

• awscodecommit
• awscognitoidentity
• awscognitouserpool (#77)
• awsdynamodb
• awsiot
• awskinesis
• awssns (#83)
• awssqs
• azureactivitylogs
• azureblobstorage (#117)
• azureeventhub (#56)
• salesforce
• http (#76)
• ocimentrics (#54)
• slack (#63)
• zendesk

Targets

• awslambda (#56)
• awssns (#56)
• awssqs (#56)
• awskinesis (#56)
• awss3 (#56)
• awseventbridge
• confluent (#75)
• datadog (#61)
• elasticsearch
• googlesheet (#65)
• hasura
• http (#78)
• infra - Pablo -
• oracle (#54)
• sendgrid
• slack (#63)
• splunk
• tekton (#65)
• twilio
• zendesk

Currently one of the images on the getting started page is not rendering correctly.

currently the docs do not get automatically deployed.