Update get-started-with-guides.md #2669

sfc-gh-kkomail · 2025-11-18T19:34:10Z

No description provided.

snowflake-github-workato · 2025-11-18T19:37:45Z

https://publish-p57963-e462098.adobeaemcloud.com/en/developers/guides/get-started-with-guides-ce5b6a9d24a1b98a06d0f63b021c5913c811cada

Note: The image uploads happen async, so they may not be uploaded yet if you click this quickly.. try again in a few minutes if so.

snowflake-github-workato · 2025-11-18T19:44:34Z

https://publish-p57963-e462098.adobeaemcloud.com/en/developers/guides/get-started-with-guides-e19e3108b7826f42674d4c73d8b7fb4e8ddb22c7

Note: The image uploads happen async, so they may not be uploaded yet if you click this quickly.. try again in a few minutes if so.

snowflake-github-workato · 2025-11-18T20:06:16Z

https://publish-p57963-e462098.adobeaemcloud.com/en/developers/guides/get-started-with-guides-6837d59c15dfb232ac4179e8d7130d0a2530a828

Note: The image uploads happen async, so they may not be uploaded yet if you click this quickly.. try again in a few minutes if so.

snowflake-github-workato · 2025-11-18T20:28:06Z

https://publish-p57963-e462098.adobeaemcloud.com/en/developers/guides/get-started-with-guides-6837d59c15dfb232ac4179e8d7130d0a2530a828

Note: The image uploads happen async, so they may not be uploaded yet if you click this quickly.. try again in a few minutes if so.

sfc-gh-annafilippova

some questions/comments about layout and structure

sfc-gh-annafilippova · 2025-11-18T20:28:56Z

site/sfguides/src/get-started-with-guides/get-started-with-guides.md

 - [SFGuides on GitHub](https://github.com/Snowflake-Labs/sfguides)
- [Learn the GitHub Flow](https://guides.github.com/introduction/flow/)
- [Learn How to Fork a project on GitHub](https://guides.github.com/activities/forking/)
+- Other relevant links to blogs, other guides, announcements etc. go here


Did you mean to add this? I don't think we want to replace two useful URLs with a non-specific message like this

seeing that you have these at the end now -- given that, does it make sense to have two related resources headings? Should this heading instead be something like "Get started quickly" or "If you prefer video instructions"... and then links to the two youtube videos?

I do think the github flow and forks are important pre-requisites so not sure if we want to relegate it to all the way at the bottom

when we preview the guide, the components of a guide section explains what basic layout details are needed:

intro (what you will learn, build etc.)

topics

conclusion (what you learned, built etc.) <-- this is just to explain the basic layout... these are instructions.

our Guide conclusion is at the bottom where I mention all important links mentioned in our guide.

I still think it's confusing to do this, and we should simplify

sfc-gh-annafilippova · 2025-11-18T20:29:33Z

site/sfguides/src/get-started-with-guides/get-started-with-guides.md


 #### Images
-![Puppy](assets/puppy.jpg)
+![](assets/puppy.jpg "Puppy")


This doesn't work for me 🤔

@sfc-gh-kkomail were you able to fix this?

yep working in preview link!

site/sfguides/src/get-started-with-guides/get-started-with-guides.md

sfc-gh-annafilippova · 2025-11-18T20:32:20Z

site/sfguides/src/get-started-with-guides/get-started-with-guides.md


 It's also important to remember that by the time a reader has completed a Guide, the goal is that they have actually built something! Guides teach through hands-on examples -- not just explaining concepts.

 ### What We've Covered


should this be here? there's a similar section below

explaining components of a guide

same as above. it's confusing

sfc-gh-annafilippova · 2025-11-18T20:32:28Z

site/sfguides/src/get-started-with-guides/get-started-with-guides.md




 ### Conclusion & Next Steps


this feels odd at the beginning of a document

explaining components of a guide

I still think this is confusing here

sfc-gh-ridasafdar · 2025-11-18T20:50:17Z

site/sfguides/src/get-started-with-guides/get-started-with-guides.md

 ### Overview 

-Please use [this markdown file](site/sfguides/src/_markdown-template/) as a template for writing your own Snowflake Guides. This example guide has elements that you will use when writing your own guides, including: code snippet highlighting, downloading files, inserting photos, and more. 
+Please use [this markdown file](https://github.com/Snowflake-Labs/sfquickstarts/tree/master/site/sfguides/src#:~:text=_imports-,_markdown,-%2Dtemplate) as a template for writing your own Snowflake Guides. This example guide has elements that you will use when writing your own guides, including: code snippet highlighting, downloading files, inserting photos, and more. 


this link doesn't route me to the right spot

these links still don't route for me so I think the path is the best way to direct folks here

sfc-gh-ridasafdar · 2025-11-18T20:51:06Z

site/sfguides/src/get-started-with-guides/get-started-with-guides.md


 This section covers the basic markdown formatting options that you will need for your QuickStart. 

 Look at the [markdown source for this sfguide](https://github.com/Snowflake-Labs/sfquickstarts/blob/master/site/sfguides/src/_template/markdown.template) to see how to use markdown to generate code snippets, info boxes, and download buttons. 


getting a 404 error with the link

this doesn't look like it was changed in this PR

updates per comments

snowflake-github-workato · 2025-11-19T00:13:16Z

https://publish-p57963-e462098.adobeaemcloud.com/en/developers/guides/get-started-with-guides-b8f316b8bac54e78e1a250237176032bc415693e

Note: The image uploads happen async, so they may not be uploaded yet if you click this quickly.. try again in a few minutes if so.

snowflake-github-workato · 2025-11-19T00:14:14Z

https://publish-p57963-e462098.adobeaemcloud.com/en/developers/guides/get-started-with-guides-b8f316b8bac54e78e1a250237176032bc415693e

Note: The image uploads happen async, so they may not be uploaded yet if you click this quickly.. try again in a few minutes if so.

sfc-gh-annafilippova · 2025-11-19T00:17:27Z

site/sfguides/src/get-started-with-guides/get-started-with-guides.md

 #### Images
-![Puppy](assets/puppy.jpg)
+
+![](assets/puppy.jpg "Cute Puppy")


this is not valid markdown, so it doesn't work

I think this comment still needs to be addressed

images are working fine in GitHub preview as well as staging links.

this is what I see as the markdown format for images:

so maybe we update this to:

if that addresses your comment @sfc-gh-annafilippova ?

snowflake-github-workato · 2025-11-19T00:42:47Z

https://publish-p57963-e462098.adobeaemcloud.com/en/developers/guides/get-started-with-guides-32259413ab326837dfc1fef02256239339ca5155

Note: The image uploads happen async, so they may not be uploaded yet if you click this quickly.. try again in a few minutes if so.

snowflake-github-workato · 2025-11-19T00:43:34Z

https://publish-p57963-e462098.adobeaemcloud.com/en/developers/guides/get-started-with-guides-32259413ab326837dfc1fef02256239339ca5155

Note: The image uploads happen async, so they may not be uploaded yet if you click this quickly.. try again in a few minutes if so.

snowflake-github-workato · 2025-11-19T19:07:51Z

https://publish-p57963-e462098.adobeaemcloud.com/en/developers/guides/get-started-with-guides-99c04ac3a8f796a9457042694b42c5b28a77671f

Note: The image uploads happen async, so they may not be uploaded yet if you click this quickly.. try again in a few minutes if so.

snowflake-github-workato · 2025-11-19T20:14:51Z

https://publish-p57963-e462098.adobeaemcloud.com/en/developers/guides/get-started-with-guides-8c9cc5ffced62e81f56f83a66e670df6deb5aa29

Note: The image uploads happen async, so they may not be uploaded yet if you click this quickly.. try again in a few minutes if so.

sfc-gh-ridasafdar · 2025-11-19T19:53:44Z

site/sfguides/src/get-started-with-guides/get-started-with-guides.md

 It is important to set the correct metadata for your Snowflake Guide. The metadata contains all the information required for listing and publishing your guide and includes the following:

 ```diff
 - REQUIRED


I think we should keep the callout for required vs optional fields

we should also list what the github actions test for (I have these in the readme) and what they are doing (e.g., file rejected if action not met)

the required/optional fields are still there... the ```diff just makes them more prominent.

Adding the actions bit in

sfc-gh-ridasafdar · 2025-11-19T19:54:43Z

site/sfguides/src/get-started-with-guides/get-started-with-guides.md

 }
 ```

 #### Info Boxes


this part is slightly confusing to me -- I think we can remove since it's very specific. I wasn't sure what you meant by "pick messages above and use this code" because I didn't see code called out

It had generic code, replaced with specific code since I have seen several Quickstarts use these types of callouts.

sfc-gh-ridasafdar · 2025-11-19T19:55:02Z

site/sfguides/src/get-started-with-guides/get-started-with-guides.md

 #### Images
-![Puppy](assets/puppy.jpg)
+
+![](assets/puppy.jpg "Cute Puppy")


I think this comment still needs to be addressed

snowflake-github-workato · 2025-11-19T22:06:02Z

https://publish-p57963-e462098.adobeaemcloud.com/en/developers/guides/get-started-with-guides-17a4aca22478686afdc2ec51f9735eb115c4d2e1

Note: The image uploads happen async, so they may not be uploaded yet if you click this quickly.. try again in a few minutes if so.

snowflake-github-workato · 2025-11-19T22:28:12Z

https://publish-p57963-e462098.adobeaemcloud.com/en/developers/guides/get-started-with-guides-70cd92302b042925541c963dfe091b1d3057ad06

Note: The image uploads happen async, so they may not be uploaded yet if you click this quickly.. try again in a few minutes if so.

snowflake-github-workato · 2025-11-19T22:34:52Z

https://publish-p57963-e462098.adobeaemcloud.com/en/developers/guides/get-started-with-guides-bf87a444c919943e4b8ba1643c125e048b42f834

Note: The image uploads happen async, so they may not be uploaded yet if you click this quickly.. try again in a few minutes if so.

snowflake-github-workato · 2025-11-21T19:49:56Z

https://publish-p57963-e462098.adobeaemcloud.com/en/developers/guides/get-started-with-guides-58c42f966fef0122b97c62cca17d2995faa135a8

Note: The image uploads happen async, so they may not be uploaded yet if you click this quickly.. try again in a few minutes if so.

sfc-gh-ridasafdar

approving so we can merge and I'll make updates to markdwon directly

sfc-gh-ridasafdar · 2025-11-21T20:00:31Z

site/sfguides/src/get-started-with-guides/get-started-with-guides.md

+this means that actual code needs to be included (not just pseudo-code or concepts).

-There are three main sub-headers in a Conclusion step:
+### Prerequisites


I wonder if adding the h1/h2/h3 considerations here is better next to each section because the number of # varies in this and can be confusing

sfc-gh-ridasafdar · 2025-11-21T20:02:29Z

site/sfguides/src/get-started-with-guides/get-started-with-guides.md

 ```
-> Adding an Info Box:
-> Pick the messages above and use this code.  This will appear as an info box.
+> [!NOTE]


this and the callout to these in the boxes above is slightly repetitive. Let's simplify and have them in one section where we say add [!NOTE], [!TIP] [!IMPORTANT] to the start of a markdown line where you want to flag something to the user.

let's leaving out warning and caution - I don't think they're needed

sfc-gh-ridasafdar · 2025-11-21T20:04:52Z

site/sfguides/src/get-started-with-guides/get-started-with-guides.md

 #### Images
-![Puppy](assets/puppy.jpg)
+
+![](assets/puppy.jpg "Cute Puppy")


this is what I see as the markdown format for images:

so maybe we update this to:

if that addresses your comment @sfc-gh-annafilippova ?

sfc-gh-ridasafdar · 2025-11-21T20:09:04Z

site/sfguides/src/get-started-with-guides/get-started-with-guides.md

+![](assets/puppy.jpg "Cute Puppy")
+

 Please DO NOT use HTML code for adding images. 


could we put this in the blue box format you have?

Please DO NOT use HTML code for adding images.

dismissing so I can make markdown updates directly

Update get-started-with-guides.md

ce5b6a9

sfc-gh-kkomail temporarily deployed to staging November 18, 2025 19:34 — with GitHub Actions Inactive

open in new window instructions

e19e310

sfc-gh-kkomail temporarily deployed to staging November 18, 2025 19:41 — with GitHub Actions Inactive

removed duplicate content

6837d59

sfc-gh-kkomail temporarily deployed to staging November 18, 2025 19:53 — with GitHub Actions Inactive

sfc-gh-kkomail marked this pull request as ready for review November 18, 2025 20:24

sfc-gh-kkomail temporarily deployed to staging November 18, 2025 20:24 — with GitHub Actions Inactive

sfc-gh-kkomail requested review from sfc-gh-annafilippova and sfc-gh-ridasafdar November 18, 2025 20:24

sfc-gh-annafilippova previously requested changes Nov 18, 2025

View reviewed changes

sfc-gh-ridasafdar reviewed Nov 18, 2025

View reviewed changes

updates per comments

b8f316b

updates per comments

sfc-gh-kkomail had a problem deploying to staging November 18, 2025 21:18 — with GitHub Actions Failure

sfc-gh-kkomail requested a review from sfc-gh-ridasafdar November 18, 2025 21:21

sfc-gh-kkomail temporarily deployed to staging November 19, 2025 00:10 — with GitHub Actions Inactive

sfc-gh-annafilippova reviewed Nov 19, 2025

View reviewed changes

new. layout update

3225941

sfc-gh-kkomail temporarily deployed to staging November 19, 2025 00:39 — with GitHub Actions Inactive

Merge branch 'master' into guides-updates

1127640

sfc-gh-annafilippova temporarily deployed to staging November 19, 2025 17:23 — with GitHub Actions Inactive

Merge branch 'master' into guides-updates

99c04ac

sfc-gh-kkomail temporarily deployed to staging November 19, 2025 19:06 — with GitHub Actions Inactive

Merge branch 'master' into guides-updates

8c9cc5f

sfc-gh-kkomail temporarily deployed to staging November 19, 2025 20:13 — with GitHub Actions Inactive

sfc-gh-ridasafdar requested changes Nov 19, 2025

View reviewed changes

Merge branch 'master' into guides-updates

17a4aca

sfc-gh-kkomail temporarily deployed to staging November 19, 2025 22:03 — with GitHub Actions Inactive

latest comments incorporated

70cd923

sfc-gh-kkomail temporarily deployed to staging November 19, 2025 22:26 — with GitHub Actions Inactive

sfc-gh-kkomail requested review from sfc-gh-annafilippova and sfc-gh-ridasafdar November 19, 2025 22:26

added 2 more industry tags

bf87a44

sfc-gh-kkomail temporarily deployed to staging November 19, 2025 22:33 — with GitHub Actions Inactive

Merge branch 'master' into guides-updates

58c42f9

sfc-gh-kkomail temporarily deployed to staging November 21, 2025 19:47 — with GitHub Actions Inactive

sfc-gh-kkomail temporarily deployed to staging November 21, 2025 19:48 — with GitHub Actions Inactive

sfc-gh-ridasafdar approved these changes Nov 21, 2025

View reviewed changes

sfc-gh-kkomail merged commit 88ca10d into master Nov 21, 2025
2 checks passed


		It's also important to remember that by the time a reader has completed a Guide, the goal is that they have actually built something! Guides teach through hands-on examples -- not just explaining concepts.

		### What We've Covered


		This section covers the basic markdown formatting options that you will need for your QuickStart.

		Look at the [markdown source for this sfguide](https://github.com/Snowflake-Labs/sfquickstarts/blob/master/site/sfguides/src/_template/markdown.template) to see how to use markdown to generate code snippets, info boxes, and download buttons.

		![](assets/puppy.jpg "Cute Puppy")


		Please DO NOT use HTML code for adding images.

Update get-started-with-guides.md #2669

Update get-started-with-guides.md #2669

Uh oh!

Conversation

sfc-gh-kkomail commented Nov 18, 2025

Uh oh!

snowflake-github-workato bot commented Nov 18, 2025

Uh oh!

snowflake-github-workato bot commented Nov 18, 2025

Uh oh!

snowflake-github-workato bot commented Nov 18, 2025

Uh oh!

snowflake-github-workato bot commented Nov 18, 2025

Uh oh!

sfc-gh-annafilippova left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

snowflake-github-workato bot commented Nov 19, 2025

Uh oh!

snowflake-github-workato bot commented Nov 19, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

snowflake-github-workato bot commented Nov 19, 2025

Uh oh!

snowflake-github-workato bot commented Nov 19, 2025

Uh oh!

snowflake-github-workato bot commented Nov 19, 2025

Uh oh!

snowflake-github-workato bot commented Nov 19, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!