Skip to content

Conversation

@johanzander
Copy link
Contributor

@johanzander johanzander commented Nov 7, 2025

Proposed change

This PR improves the Growatt Server integration documentation to meet bronze tier quality scale requirements and provide better user guidance.

Changes:

  • Add removal instructions - Required for bronze tier docs-removal-instructions rule
  • Add troubleshooting section - Addresses common user issues:
    • Account lockout and need to accept terms in ShinePhone app
    • Rate limiting workarounds and prevention strategies
    • How to disable integration during HA restarts to avoid lockouts
    • Wrong server selection guidance
  • Add known limitations section - Documents rate limiting with username/password authentication
  • Improve clarity and accuracy:
    • Changed "sensor logs into" to "integration connects to"
    • Use "entities" instead of just "sensors" for better accuracy
    • Fixed markdown linter warnings (wrapped bare URLs in backticks)

Type of change

  • Spelling, grammar or other readability improvements (current branch).
  • Adjusted missing or incorrect information in the current documentation (current branch).
  • Added documentation for a new integration I'm adding to Home Assistant (next branch).
  • Added documentation for a new feature I'm adding to Home Assistant (next branch).
  • Removed stale or deprecated documentation.

Additional information

  • Link to parent pull request in the codebase:
  • Link to parent pull request in the Brands repository:
  • This PR fixes or closes issue: fixes #

Checklist

  • This PR uses the correct branch, based on one of the following:
    • I made a change to the existing documentation and used the current branch.
    • I made a change that is related to an upcoming version of Home Assistant and used the next branch.
  • The documentation follows the Home Assistant documentation standards.

- Add removal instructions section (required for bronze tier)
- Add troubleshooting section with common issues and solutions
  - Account lockout and terms acceptance in ShinePhone app
  - Rate limiting workarounds
  - HA restart prevention tips
- Add known limitations section documenting rate limiting
- Improve clarity: change "sensor logs into" to "integration connects to"
- Use "entities" instead of just "sensors" for better accuracy
- Fix markdown linter warnings by wrapping bare URLs in backticks
@home-assistant home-assistant bot added the current This PR goes into the current branch label Nov 7, 2025
@netlify
Copy link

netlify bot commented Nov 7, 2025

Deploy Preview for home-assistant-docs ready!

Name Link
🔨 Latest commit a3698f4
🔍 Latest deploy log https://app.netlify.com/projects/home-assistant-docs/deploys/690e7da0b050cd00084fdf4c
😎 Deploy Preview https://deploy-preview-41668--home-assistant-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@johanzander johanzander marked this pull request as draft November 7, 2025 14:58
@johanzander johanzander marked this pull request as ready for review November 7, 2025 15:04
Comment on lines 22 to 25
- For users in China: `https://openapi-cn.growatt.com/`
- For users in North America: `https://openapi-us.growatt.com/`
- For users in other regions: `https://openapi.growatt.com/`
- SMTEN server: `http://server.smten.com/`
Copy link
Contributor

Choose a reason for hiding this comment

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

I'm not sure if it is best practice to have links within backticks. While it may visually look better, this will no longer keep the link clickable and a user would have to either manually enter or copy the URL.

@johanzander
Copy link
Contributor Author

Good catch on the formatting concern! However, these URLs shouldn't be clickable because they're API endpoints that users need to copy and paste into their Growatt integration configuration - they're not web pages meant to be visited in a browser.

If clicking these URLs was encouraged, users would try to visit them in their browser (which isn't useful) instead of copying them into their HA configuration. Ive changed to code blocks that users can copy.

What do you think about this? Is it better or do you want me to move back to clickable links?

@ogruendel
Copy link
Contributor

Good catch on the formatting concern! However, these URLs shouldn't be clickable because they're API endpoints that users need to copy and paste into their Growatt integration configuration - they're not web pages meant to be visited in a browser.

If clicking these URLs was encouraged, users would try to visit them in their browser (which isn't useful) instead of copying them into their HA configuration. Ive changed to code blocks that users can copy.

What do you think about this? Is it better or do you want me to move back to clickable links?

Ah, I see. Sorry, didn't catch that the first time. I think in that case it does make sense to make the links non-clickable and the solution with embedding them in a text block, which allows copying is probably the best way to approach this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

current This PR goes into the current branch

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants