docs: guide quick start app creation using the slack cli #2535
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #2535 +/- ##
=======================================
Coverage 93.35% 93.35%
=======================================
Files 37 37
Lines 7575 7575
Branches 664 664
=======================================
Hits 7072 7072
Misses 498 498
Partials 5 5 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
| @@ -1,493 +1,256 @@ | |||
| --- | |||
There was a problem hiding this comment.
you're going to hate this lol, but we name these .md files! docusaurus treats .md files as .mdx files but with more forgiving syntax. i can't find the docs on this but this page has interesting side thoughts
There was a problem hiding this comment.
🫡 No! In fact quite the opposite. .mdx is not a familiar extension to me so I am glad to make this change.
FWIW the linked page is confusing to me and I don't know which markdown format is used in practice but I am hoping most for what's forgiving 🙏
By default, Docusaurus v3 uses the MDX format for all files (including
.mdfiles) for historical reasons.
.mdfiles will use the CommonMark format
docs/content/getting-started.mdx
Outdated
| ``` | ||
|
|
||
| Change your Bolt initialization code and restart the app. | ||
| After the app has started, celebrate, then interrupt the process with `^C` to stop it for now. |
docs/content/getting-started.mdx
Outdated
|
|
||
| app.logger.info('⚡️ Bolt app is running!'); | ||
| })(); | ||
| ```sh |
There was a problem hiding this comment.
sh isn't default in docusaurus i believe. if you'd be so kind, add this to the docusaurus.config.js
themeConfig: // already exists
...
prism: { // already exists
darkTheme: prismThemes.dracula, // already exists
additionalLanguages: ['bash'] // put this here pls
},
There was a problem hiding this comment.
"sh" is an alias for bash syntax so you dont need to change that
There was a problem hiding this comment.
@lukegalbraithrussell Nice catch! I'm surprised bash is not a default language but it was no problem adding this in b61e880 📚
docs/content/getting-started.mdx
Outdated
|
|
||
| Let's add a handler to send a followup message when someone clicks the button: | ||
| The defaults included leave opportunities abound, so to personalize this app let's now update the app name then respond with a kind farewell. |
There was a problem hiding this comment.
this reads like taylor's docs voice and makes me nostalgic <3
There was a problem hiding this comment.
Imitation is the highest form of learning - or something somewhat similar I think - from one of the best 🤩
docs/sidebars.js
Outdated
| { | ||
| type: 'category', | ||
| label: 'Getting Started', | ||
| items: ['getting-started', 'building-an-app'], | ||
| }, |
There was a problem hiding this comment.
one idea is to match this navbar to the docs sidebar where it's like
Bolt JS
Quickstart
---
Building an app
Slack API Calls
...
There was a problem hiding this comment.
Moving this to the top of the sidebar is a great idea! I don't mean to be biased, but this makes getting started even faster!
docs/content/getting-started.mdx
Outdated
|
|
||
| If you don’t already have a project, let’s create a new one. Create an empty directory and initialize a new project: | ||
| <Tabs groupId="cli-or-terminal"> |
There was a problem hiding this comment.
i'm tripping ove this a bit because the cli is in the terminal. is there another delineator to use?
There was a problem hiding this comment.
@lukegalbraithrussell This is so confusing to me too. I don't have a better suggestion at the moment since:
cliis for the Slack CLIterminalis for both direct commands and the browser
IMO this difference can be understood alright in the tab titles, but that doesn't make it less confusing... 🤔
docs/content/getting-started.md
Outdated
| }); | ||
| ``` | ||
|
|
||
| Once the file is saved, restart your app to make sure the latest changes are being used, then go back to channel and say "goodbye". |
There was a problem hiding this comment.
suggestion: Since this is a Getting Started guide, I think it's best to hold the developer's hand all the way. I'd suggest that we show the command to run your app rather than having the developer figure out how to "restart your app". This would require a <TabItem> for the CLI / Terminal to show the slack run and npm start commands again and explain to open a DM with their bot and send the "goodbye" text.
…ollowing Co-authored-by: Michael Brooks <mbrooks@slack-corp.com>
|
@mwbrooks @lukegalbraithrussell @technically-tracy After all of these incredible reviews and suggestions and even a release of the latest Slack CLI v3.3.0 I'm feeling excited for these changes. Following the steps of both the "Slack CLI" and "Terminal" guides have proven alright in testing, but all feedback on this or organization otherwise remains so appreciated 🙏 ✨ Depending on how following reviews go I am hoping we can release this soon and perhaps follow up with enhancement as seen best. Hopes of a similar guide for Bolt Python and reworks of the "Building an app" page await with excitement 👾 |
Yes definitely - I've already put this on our road map for when these changes are finalized! 📝 |
There was a problem hiding this comment.
✅ Looking good @zimeg 👏🏻 Thank you for writing the Quickstart Guide!
🧪 I've manually tried both the Slack CLI and Terminal steps. Things work and flow well together.
👥 I'd suggest we wait until @lukegalbraithrussell or @technically-tracy throws an approval on this PR as well. Personally, I think this is a good first pass and the docs team can come in later to give it the consistent voice that we have on our other docs. But, I'll let them decide when the first edition is ready to ship! 📚
Co-authored-by: Michael Brooks <mbrooks@slack-corp.com>
|
@technically-tracy Love to hear it! As always, please feel free to loop me in if you'd like 📚 ✨ @mwbrooks Great catches more! Thanks for testing and sharing how you read in a review 👁️🗨️
This sounds good to me and I agree that some of word choices here might be off putting 😉 |
|
@technically-tracy @haleychaas Apologies for this I hope polite bump, but before we merge this I was wondering if another review is possible or if other happenings related to all things documentation might be needed in shipping this? |
Sure thing, I'll take another look today! 👀 |
|
@technically-tracy Such kind words! I'm glad we've brought the quickstart to this point and I think now is a good time to release it 🚢 💨 @technically-tracy @lukegalbraithrussell @mwbrooks Thank y'all all for the thorough reviews and suggestions once more. These were incredible perspectives and I feel to be a much better writer now 📚 ✨ |
Summary
This PR contains a WIP guide for a quick start getting started experience that leverages the Slack CLI.
Reviewers
Inspect these elements in a web browser and this branch: http://localhost:3000/bolt-js/getting-started
Notes
diffis not kind to the reviewer but the Quick start replaces the current Getting started guide, which was moved to be Building an app. No updates were made to the existing guide at this time.Requirements