snowplow/documentation

Snowplow Documentation Website

documentation's Issues

Some diagrams that have connections with black lines are unreadable when using the available darkmode

The diagram at the bottom of this page is an example:
https://github.com/snowplow/documentation/blob/main/docs/destinations/warehouses-and-lakes/rdb/index.md

In this screenshot, you can see that it is near impossible to read the diagram in dark mode.

Possible solutions:

• Do nothing (poor user experience, rely on users turning dark mode on/off to view diagrams)
• Set a standard for all diagrams to be on a white background instead of a transparent background (impact seems minimal to image file size however it would impact the 'dark mode' experience; also a large effort)
• change the color of the lines in all diagrams (this could be a large effort)
• Remove the option for users to turn on dark mode (likely counter productive since it is available and preferred by some users)

Add maxLength property to the docs page

Hi Team,

Can we please add the maxLength property to the canonical fields docs page?
This will help customers understand the failure reasons and max length allowed for canonical properties.

https://docs.snowplow.io/docs/understanding-your-pipeline/canonical-event/
https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow/atomic/jsonschema/1-0-0

Move leaf pages from `page/index.md` to `page.md`

Because of the migration process, all pages are currently named index.md. This can be a bit confusing when editing.
A nice option is to switch from page/index.md to just page.md. We would still keep index.md naming in two situations:

• When the page has subpages. The alternative could be to use page.md + page/<subpages>, but this seems clunky and makes moving pages around a 2-step process.
• When the page has images. One alternative could be to use page.md + page/images/... — this has the same downsides as the above. Another alternative is to go with page.md and move the images 1 level up to a shared images directory. However, this will make it difficult to move the page later, because we would need to figure out which images it needs.

Here’s a script (sorry, in fish shell) to do this:

for f in (git ls-files '**/index.md'); if [ (ls (dirname $f) | wc -l | tr -d ' ') = 1 ]; git mv $f (echo $f | sed s!/index.md!.md!); end; end

I’ve tried it and as of this writing it moves 469 files. The good news is that only 5 (!) links break, which could all be fixed by hand.

`category` should be required property for ecommerce product entity

Hi!

The documentation for product entity has category as optional, but it's defined as mandatory in the schema.

Cheers
Andreas

Marking deprecated fields

Suggestion to mark os_family, os_name and os_manufacturer fields as deprecated, and suggesting to use alternative (e.g. YAUAA context):

documentation/docs/understanding-your-pipeline/canonical-event/index.md

Lines 111 to 113 in a6939b1

	| `os_name` _(not available in BDP Cloud)_ | text | Name of operating system | No | 'Android' |
	| `os_family` _(not available in BDP Cloud)_ | text | Operating system family | No | 'Linux' |
	| `os_manufacturer` _(not available in BDP Cloud)_ | text | Company responsible for OS | No | 'Apple' |

Issue: Feedback Text Area Validation Missing in Footer

It looks like you're describing an issue related to feedback validation in the footer of a documentation website. Here's a refined version of your issue description:

---

Issue: Feedback Form Validation Missing in Footer

Steps to Reproduce:

1. Navigate to the footer of the documentation website.
2. Locate the feedback form.

Description:
Upon attempting to submit feedback without any validation for user input, the system displays "Thanks for the feedback" even if the user has not entered any feedback.

Expected Behavior:
The feedback form should include validation to ensure that users have entered something before displaying the "Thanks for the feedback" message.

@Lakszy

trackTransactionError: transaction object requires `total_quantity`

Hi!
The example for trackTransactionError on your docs page doesn't work as it is missing total_quantity inside the transaction object.

https://docs.snowplow.io/docs/collecting-data/collecting-from-own-applications/javascript-trackers/javascript-tracker/javascript-tracker-v3/plugins/snowplow-ecommerce/#tracktransactionerror

Relevant schema:
https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow.ecommerce/transaction/jsonschema/1-0-0

Cheers
Andreas

Update Micro docs for 1.3.3

Add dbt privs required documentation

Explore what’s the best way to add version selectors

Many trackers and other modules are versioned, and we currently manage those pages in an ad-hoc way. Docusaurus natively supports versioning (https://docusaurus.io/docs/versioning), and we could benefit from this functionality.

Something to take into account is that we have a lot of versioned modules. I think this means we’d have to go with one of the options below.

Option 1

Use docs multi-instance (https://docusaurus.io/docs/docs-multi-instance), with an instance for each module. Note:

• I am not sure if instances can sit under a common URL prefix, or if each has to be at the root (nothing that can’t be solved with a bunch of redirects though).
• By default this will show all the version selectors on all pages, which is not practical. See facebook/docusaurus#4389 (comment) for an example of how that can be solved.
• Currently (September 2022) Markdown links are not checked across instances. I guess we can live with that.

Option 2a

Make a different Docusaurus setup for each module (still in this repo), and have the master Docusaurus site link to the sub-sites. This is similar to what MongoDB seems to be doing: once you navigate into a specific module, like mongocli, it does not retain the navigation from the parent site (but does have versioning). Note:

• Faster build times
• Much more contrived build and deploy setup
• Markdown links also not checked between sites

Option 2b

Same as 2a, but the docs for each module live in their own repo and are deployed there. Note:

• Faster build times
• Can update individual modules’ docs without updating the whole thing
• Links also not checked
• It will be a huge PITA to set up, and a huge PITA to do any sort of mass-replacement in the text. I guess this alone should disqualify this option

Add Scala tracker 2.0.0 docs

Migrate API docs to openapi docs structure where possible

https://github.com/PaloAltoNetworks/docusaurus-openapi-docs or possibly https://github.com/cloud-annotations/docusaurus-openapi ?

At least explore posibility for Snowplow micro, I think it works with Swagger 2.0 and OpenAPI 3.x, which I don't know what of our APIs are in terms of trackers and tools.

Update docs for latest gtm v3 tag and variable

After releasing:
Snowplow v3 Tag v1.1.0
Snowplow v3 Settings Variable v1.2.0

Dark Mode Image Issues Tracking

Summary

This is a meta-issue to track identification and fixing of issues with images in dark mode such as those raised in #279.

When you find an image that does not work in both light and dark mode, and are unable to fix it in a PR, comment on this issue with the link to the page and we will.

In the meantime, if possible please also raise a PR that adds a temporary background to the image by replacing the image link with the below, which will ensure it is visible while we work to replace the image.

  <div style={{"background-color": '#F2F4F7'}}>
  <img src={require("./images/IMAGE_NAME.png").default}/>
  </div>

Open Issues:

• [ ]

Temporary fixes:

• [ ]

Tidy tracker protocol page

The tracker protocol page is currently hard to consume and doesn't make it particularly easy to build something on top of tp2.

There are also a number of examples, but they are all GET requests which are rarely used now in favour of POST.

Clean up reusable blocks

The reusable blocks were imported from the previous platform and need some clean up:

• Inline the ones that are only used once
• Replace the tracker maintenance blocks with the <Badges> component
• See if there is anything else that does not make sense

Remove outdated links from headers

Example:

## [](https://github.com/snowplow/snowplow/wiki/Android-and-Java-Tracker#4-tracking-specific-events)4. Tracking specific events

yaml syntax highlighting not rendering

When a code block specifies a yaml language tag these are not rendered out correctly on the published site despite being a supported prism default language. It fails both with yml and yaml as the language names.

Example:
https://docs.snowplow.io/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-configuration/#model-configuration

documentation/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-configuration/index.md

Lines 145 to 155 in 6c3dec2

	```yml
	# dbt_project.yml
	...
	vars:
	snowplow_web:
	snowplow__backfill_limit_days: 60
	snowplow_media_player:
	snowplow__percent_progress_boundaries: [20, 40, 60, 80]
	```

Update Flutter tracker docs for v0.2.0

For any improvements/clarifications I want to add to the docs, as I go through and learn Flutter/about our Flutter tracker.

Fix anchor links

When migrating from the previous platform, many links got converted to This_Format, whereas Docusaurus actually generates anchor ids in this-format. Because of this, many anchor links don’t work. See git grep '\((/.+)?#[a-zA-Z0-9]+_[a-zA-Z0-9_]+' '*.md' for some examples.

quickstart for open source on aws - iglu_server_dns_name missing protocol

Hi,

I've used the default terraform modules for AWS:

1. deployed iglu server
2. deployed pipeline with using the iglu_server_dns_name output

everything works well (example & creating custom events), but the ingestion of custom don't work --> they end up with RepoFailure.

The iglu_server_dns_name output dont contain a protocol (http / https), and its also missing in the documentation.
Since it used later for the iglu resolver config, the pipeline will throw ResolutionError messages like:

"errors":[{"error":"RepoFailure","message":"no protocol: sp-iglu-lb-

It would be great to at least add short info the description OR add additional input var for protocol.

Thx!