Skip to content

docs(app): add dedicated Troubleshooting page#3696

Merged
EtienneM merged 1 commit intomasterfrom
feat/rework-troubleshooting-pages
May 5, 2026
Merged

docs(app): add dedicated Troubleshooting page#3696
EtienneM merged 1 commit intomasterfrom
feat/rework-troubleshooting-pages

Conversation

@benjaminach
Copy link
Copy Markdown
Contributor

@benjaminach benjaminach commented Apr 29, 2026

This PR reorganizes the troubleshooting documentation to make first deployment
issues easier to identify and route to the right detailed page.

Main changes:

  • Move application troubleshooting content into a dedicated
    platform/app/troubleshooting section.
  • Replace the former broad Common Deployment Errors page with more focused
    pages:
    • Deployment Issues for source fetching, technology detection, and build
      failures.
    • Boot Errors for start, timeout, and postdeploy hook errors.
    • Runtime Issues for problems happening after the app is running.
  • Rename and move the former Application Crash page into the new runtime
    troubleshooting section.
  • Add shared language start-page links through a reusable include.
  • Update related links from Getting Started, Procfile, postdeploy hook, CLI,
    and container management pages.

Why

The previous structure mixed several troubleshooting phases in pages that were
hard to scan and not always clearly named. This change separates deployment,
startup, and runtime issues so users can first identify where the failure
happens, then follow the relevant detailed guide.

Notes

  • The old common-deployment-errors page is intentionally removed.
  • Existing redirect entries were left untouched; new redirects were appended at
    the end of the 301 section.

This PR continues the work initiated by @sc-zenokerr in #3485.

@benjaminach benjaminach marked this pull request as draft April 29, 2026 14:35
@benjaminach
Copy link
Copy Markdown
Contributor Author

benjaminach commented May 4, 2026

From the current draft, I already know that @Frzk does not like the "Quick Resolution Guide" in the "Getting Started" section.

Since "Common deployment errors" have been moved to the dedicated "Troubleshooting" section, I chose to keep a page in "Getting Started" to help customers understand the stack and identify common sources of issues.

If we decide not to keep this "Quick Resolution Guide", we can still remove it from that section.

@SC-Samir
Copy link
Copy Markdown
Contributor

SC-Samir commented May 4, 2026

The PR is ready for review or still in draft?

@benjaminach benjaminach marked this pull request as ready for review May 4, 2026 12:33
@benjaminach
Copy link
Copy Markdown
Contributor Author

The PR is ready for review or still in draft?

Ready for review 👌 Thanks

@Frzk
Copy link
Copy Markdown
Contributor

Frzk commented May 4, 2026

@benjaminach: I've just pushed the new Jekyll tag in this branch, so you may want to wait until I can put it on all concerned pages?

@semgrep-code-scalingo
Copy link
Copy Markdown

Legal Risk

The following dependencies were released under a license that
has been flagged by your organization for consideration.

Recommendation

While merging is not directly blocked, it's best to pause and consider what it means to use this license before continuing. If you are unsure, reach out to your security team or Semgrep admin to address this issue.

MPL-2.0

Copy link
Copy Markdown
Contributor

@Frzk Frzk left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • I feel like the new Troubleshooting pages are great, but maybe lack a bit of polish/homogeneity pass. This can come later.
  • Not found of the "Quick Resolution" page (more below)
  • A very little nitpicky, non-blocking suggestion.

Comment thread src/_posts/platform/getting-started/2000-01-01-first-steps.md Outdated
Comment thread src/_posts/platform/getting-started/2000-01-01-quick-resolution-guide.md Outdated
@benjaminach
Copy link
Copy Markdown
Contributor Author

  • I feel like the new Troubleshooting pages are great, but maybe lack a bit of polish/homogeneity pass. This can come later.

In this pass I tried to limit changes to the structuration of the pages, but indeed, we will have to rework the content a bit further.

Copy link
Copy Markdown
Member

@EtienneM EtienneM left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

praise: I love the timeline 🤩

praise: thanks a lot for this refacto

I just added a bunch of suggestions, but already approving.

Comment thread src/_posts/platform/app/troubleshooting/2000-01-01-boot-errors.md
Comment thread src/_posts/platform/app/troubleshooting/2000-01-01-boot-and-startup-errors.md Outdated
Comment thread src/_posts/platform/app/troubleshooting/2000-01-01-boot-errors.md
Comment thread src/_posts/platform/app/troubleshooting/2000-01-01-boot-and-startup-errors.md Outdated
Comment thread src/_posts/platform/app/troubleshooting/2000-01-01-deployment-issues.md Outdated
Comment thread src/_posts/platform/app/troubleshooting/2000-01-01-runtime-issues.md Outdated
@EtienneM EtienneM force-pushed the feat/rework-troubleshooting-pages branch from 2e7198a to 2fd50d5 Compare May 5, 2026 12:39
@EtienneM EtienneM changed the title Improve troubleshooting pages docs(app): add dedicated Troubleshooting page May 5, 2026
@EtienneM EtienneM force-pushed the feat/rework-troubleshooting-pages branch from 2fd50d5 to 1fb79b4 Compare May 5, 2026 12:45
@EtienneM EtienneM merged commit d3a8fbf into master May 5, 2026
4 checks passed
@EtienneM EtienneM deleted the feat/rework-troubleshooting-pages branch May 5, 2026 12:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants