docs: concept focused nav #2302

lukegalbraithrussell · 2024-10-25T01:26:34Z

Summary

Applies to both English and Japanese sites.

The huge file count and lines is because I updated the folder structure to more accurately reflect the new docs organization

sorts pages into categories. I followed Kaz's outline with one change: I placed "App Home" in "Interactivity /Shortcuts"
consolidates deprecated steps from apps into one page.
consolidates getting started pages into one with tabs (HTTP / socket mode)

Requirements (place an `x` in each `[ ]`)

I've read and understood the Contributing Guidelines and have done my best effort to follow them.
I've read and agree to the Code of Conduct.

codecov · 2024-10-25T01:28:24Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 92.48%. Comparing base (e51960b) to head (2118ff1).
Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2302   +/-   ##
=======================================
  Coverage   92.48%   92.48%           
=======================================
  Files          36       36           
  Lines        7466     7466           
  Branches      651      651           
=======================================
  Hits         6905     6905           
  Misses        553      553           
  Partials        8        8

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

lukegalbraithrussell · 2024-10-25T18:50:50Z

docs/content/concepts/assistant.md

@@ -0,0 +1,186 @@
+---


Grabbing this from other PR so I can display Assistant in Nav

If we can merge this change ealier than the assistant page PR, removing this from this PR, merging this PR without assistant page, and then adjusting the assistant page PR to be compatible with this new structure may be smoother

docs/i18n/ja-jp/docusaurus-plugin-content-docs/current.json

lukegalbraithrussell · 2024-10-25T19:01:16Z

docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/getting-started.mdx

@@ -9,11 +9,7 @@ lang: ja-jp



@seratch I tried combining the Socket Mode and HTTP versions. Can you read it to make sure I did so properly?

lukegalbraithrussell · 2024-10-25T19:01:58Z

docs/src/css/custom.css

+.tabs-container {
+  border: 2px solid var(--ifm-hr-background-color); /* Adjust the color and thickness as needed */
+  border-radius: 5px; /* To give rounded corners */
+  padding: 0.5em; /* To add spacing inside the tab */
+}


This adds an outline around the tabs container so you can tell when the tabbed section ends

lukegalbraithrussell · 2024-10-25T19:04:58Z

docs/sidebars.js

+      label: "Bolt for JavaScript",
+      className: "sidebar-title",
+    },
+    "getting-started",


This is the sidebar organization

seratch

Thank you for working on this so quickly!

seratch · 2024-10-28T01:05:27Z

docs/content/concepts/assistant.md

@@ -0,0 +1,186 @@
+---


If we can merge this change ealier than the assistant page PR, removing this from this PR, merging this PR without assistant page, and then adjusting the assistant page PR to be compatible with this new structure may be smoother

docs/content/getting-started.mdx

docs/i18n/ja-jp/docusaurus-plugin-content-docs/current.json

filmaj

Left my first round of comments! Thanks for doing this, I think it's a big improvement.

filmaj · 2024-10-28T15:51:45Z

docs/content/concepts/event-listening.md

@@ -4,7 +4,7 @@ lang: en
 slug: /concepts/event-listening
 ---

-You can listen to [any Events API event](https://api.slack.com/events) using the `event()` method after subscribing to it in your app configuration. This allows your app to take action when something happens in Slack, like a user reacting to a message or joining a channel.


I know this isn't exactly part of your PR here but figured I'd mention it: the <detail> at the bottom of this page calls out a specific thing about the message() event listening. Perhaps we should move that to the message-listening.md page instead? I also think we can start 'unfurling' these <detail> blocks, since the pages now are much shorter and more focussed. Often, when interacting with devs about various topics, I find I have to explicitly point them to docs content nested inside these folded-up <detail> sections for content relevant to their issue or question.

Makes sense to me!

filmaj · 2024-10-28T15:55:33Z

docs/sidebars.js

+    },
+    {
+      type: "category",
+      label: "Interactivity & Shortcuts",


I'm unsure if this label is descriptive or broad enough; will developers understand the breadth of UI surfaces and features this category contains? Buttons, dropdown menus, modal UIs, shortcuts, slash commands... there's a lot here! What about "App UI & Interactivity"? I think that's slightly broader, and then if we can make sure there are descriptions of each of these UIs/features in each sub-page as an intro blurb, I think that would work well. What do you think?

filmaj · 2024-10-28T15:57:39Z

docs/content/concepts/acknowledge.md

I think one thing we should call out in this document is that, while these interactivity and shortcut-related app features do require acknowledgement of Slack events, the Events API handlers do not because Bolt automatically acknowledges them. Perhaps this particular convenience/magic needs reinforcement on this page and possibly also on the 'listening to messages' and 'listening to events' pages?

filmaj · 2024-10-28T15:58:22Z

docs/content/concepts/commands.md

Is there some end-user or api.slack.com document we can link to for Slash Commands?

filmaj · 2024-10-28T15:59:45Z

docs/content/concepts/action-listening.md

@@ -12,7 +12,7 @@ You’ll notice in all `action()` examples, `ack()` is used. It is required to c

 :::info

-Since v2, message shortcuts (previously message actions) now use the `shortcut()` method instead of the `action()` method. View the [migration guide for V2](/tutorial/migration-v2) to learn about the changes.
+Since v2, message shortcuts (previously message actions) now use the `shortcut()` method instead of the `action()` method. View the [migration guide for V2](/migration/migration-v2) to learn about the changes.


Let's just get rid of this callout; we're on v4 now. No need to link or call out things specific about a version that was last released 4 years ago.

filmaj · 2024-10-28T16:01:02Z

docs/content/concepts/action-listening.md

For the shortcuts and commands pages, we combine both listening and responding into one doc. Maybe we could do the same for actions? I.e. combine action-listening.md and action-respond.md?

docs/sidebars.js

filmaj · 2024-10-28T16:03:48Z

docs/content/concepts/options.md

I'd like to change the title of this document so it's a bit more obvious what it's about. "Options" on its own lacks context. It's about dynamic rendering of dropdown select menu options - I'd like to make that more clear in this document as well as in the sidebar.

filmaj · 2024-10-28T16:06:11Z

docs/sidebars.js

-        'advanced/logging',
-        'advanced/custom-routes',
-        'advanced/receiver',
+        "concepts/authorization",


I'd put the authorization article after the authenticating-with-OAuth one, since the latter is a pre-req for using the former.

Co-authored-by: Kazuhiro Sera <seratch@gmail.com>

…updated-nav

lukegalbraithrussell added 2 commits October 24, 2024 18:20

docs: reorg nav

6b3a430

docs: added assistant

5cbb4f8

docs: moving stuff around

ac518e1

lukegalbraithrussell commented Oct 25, 2024

View reviewed changes

lukegalbraithrussell added 2 commits October 25, 2024 11:53

add translation json

b99edba

docs: remove superfluous generated translation json

9c53077

lukegalbraithrussell commented Oct 25, 2024

View reviewed changes

docs/i18n/ja-jp/docusaurus-plugin-content-docs/current.json Outdated Show resolved Hide resolved

lukegalbraithrussell commented Oct 25, 2024

View reviewed changes

lukegalbraithrussell marked this pull request as ready for review October 25, 2024 19:05

lukegalbraithrussell requested review from filmaj, seratch and a team October 25, 2024 19:06

seratch added the discussion M-T: An issue where more input is needed to reach a decision label Oct 28, 2024

seratch added this to the 4.x milestone Oct 28, 2024

seratch approved these changes Oct 28, 2024

View reviewed changes

technically-tracy approved these changes Oct 28, 2024

View reviewed changes

filmaj reviewed Oct 28, 2024

View reviewed changes

lukegalbraithrussell and others added 4 commits October 28, 2024 13:32

Apply suggestions from code review

9268140

Co-authored-by: Kazuhiro Sera <seratch@gmail.com>

feedback from PR

4041ac6

Merge branch 'main' of https://github.com/slackapi/bolt-js into docs-…

0f2e6fd

…updated-nav

Merge branch 'main' into docs-updated-nav

2118ff1

lukegalbraithrussell added the docs M-T: Documentation work only label Oct 29, 2024

lukegalbraithrussell merged commit d3fe549 into main Oct 29, 2024
20 checks passed

lukegalbraithrussell deleted the docs-updated-nav branch October 29, 2024 15:23

filmaj modified the milestones: 4.x, 4.1 Nov 1, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: concept focused nav #2302

docs: concept focused nav #2302

lukegalbraithrussell commented Oct 25, 2024 •

edited

Loading

codecov bot commented Oct 25, 2024 •

edited

Loading

lukegalbraithrussell Oct 25, 2024

seratch Oct 28, 2024

lukegalbraithrussell Oct 25, 2024

lukegalbraithrussell Oct 25, 2024

lukegalbraithrussell Oct 25, 2024

seratch left a comment

seratch Oct 28, 2024

filmaj left a comment

filmaj Oct 28, 2024

lukegalbraithrussell Oct 28, 2024

filmaj Oct 28, 2024

filmaj Oct 28, 2024

filmaj Oct 28, 2024

filmaj Oct 28, 2024

filmaj Oct 28, 2024

filmaj Oct 28, 2024

filmaj Oct 28, 2024

docs: concept focused nav #2302

docs: concept focused nav #2302

Conversation

lukegalbraithrussell commented Oct 25, 2024 • edited Loading

Summary

Requirements (place an x in each [ ])

codecov bot commented Oct 25, 2024 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

seratch left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

filmaj left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lukegalbraithrussell commented Oct 25, 2024 •

edited

Loading

Requirements (place an `x` in each `[ ]`)

codecov bot commented Oct 25, 2024 •

edited

Loading