Improve Workspaces example configuration and debugging guidance

Problem to solve

The current Workspaces example devfile config causes some issues for users:

• The example devfile uses an image that lacks development tools, such as Yarn, causing postStart commands to fail with "not found" errors.
• Users struggle to understand why postStart commands fail because:
  • Logs show "Finished running" even when commands fail.
  • Log locations are not clearly documented.
  • No guidance on how to debug postStart issues.
• The postStart logs indicate completion without indicating success/failure status

Further details

Use cases and scenarios:

• Developers setting up Workspaces for frontend projects requiring Node.js/yarn.
• Teams configuring devfiles for projects with specific tooling requirements.
• Users debugging failed postStart commands.

Current user journey problems:

1. User follows example configuration from docs.
2. postStart commands fail silently (yarn not found).
3. User assumes everything worked because logs show "Finished running".
4. User discovers the issue only when trying to access the application.
5. User needs to hunt through multiple log files to find actual error messages.

Proposal

• Update example configuration:

  • Use a more complete base image that includes common development tools or provide clear guidance on installing dependencies in postStart.

• Improve debugging docs:

  • Add clear section on "Debugging postStart Commands"
  • Document log file locations. For example, /projects/workspace-logs/poststart-stdout.log and poststart-stderr.log
  • Explain how to access logs through VS Code File menu.
  • Add troubleshooting topics.

• Enhance logging clarity:

  • Document that "Finished running" doesn't mean "completed successfully".
  • Add note about checking logs for errors.

Additional content to consider:

• Create comprehensive guide sections:

  • "Choosing the right base image" guide.
  • "Setting up custom images" tutorial.
  • "Common postStart patterns" examples.

• Add practical examples:

  • Frontend project setup (Node.js/yarn/npm)
  • Backend project setup (Python/Ruby/etc.)
  • Multi-language project configurations

Other links/references

• Related epic for broader Workspaces adoption: Enable Workspaces Dogfooding for non-GDK Engine... (&17034)
• Original Slack discussion thread