GitHub Pages or GitHub Wiki

[BDVGitHub]

Is it possible to use GitHub Pages or GitHub Wiki
So that not everything is included in the Readme.md file but only the necessary to install and the detailed info user can find in GitHub pages or GitHub Wiki. This also makes it easier to navigate for an exmple to a section how to contribute.
Because now its hard to find my way through the documentation and can't find for example https://gitlocalize.com/repo/10621 to add a language.

[autoSteve]

An interesting prospect, given the size of that documentation.

There are an awful lot of questions asked in discussions here where the answer is already in README.md, indicating that the information may be too hard to find, or could be better organised.

The flip side to the, "Just ask here" argument is maybe that answer is a lack of effort. If that is the reason then one would need to ask, "Why go to the effort for something that is not being read?"

[BJReplay]

Come on, you suggested using GitLocalize.

I didn't tag you, @BDVGitHub, but I did reply to your discussion, so you would have been notified unless you changed your subscription settings from the default.

Anything is possible, but if you don't read subscription notifications for discussions that you start, then I am not sure that creating another documentation format is the best solution.

[BDVGitHub]

If you look at other repo's using GitHub Wiki or GitHub Pages for me its easier to read.

For example:
Minimal README https://github.com/serbanb11/bosch-homecom-hass
Extended documentation in Wiki : https://github.com/serbanb11/bosch-homecom-hass/wiki

Minimal README: https://github.com/bramstroker/homeassistant-powercalc
Extende documentation in Pages: https://docs.powercalc.nl/

For GitLocalize its correct that it was easy to find for me, but I can understand that for others its not that easy.
Beacause they probably look in the README where its not, but they have to search the right topic in discussions.
Normelly you can find this in the section: contribute in the docomuntation.

Also the chapter Changes takes up a large portion of the README.
https://github.com/BJReplay/ha-solcast-solar?tab=readme-ov-file#changes

So it might be easier for people when the README is shorter and the extended info is in a GitHub Wiki or Pages.

[autoSteve]

True story. "polling cycle" is mentioned in several pages, yet is unsearchable at GitHub. Only the page titles are searchable with no full text search.

Makes this a hard, "No" from me, too.

---

Suggest README.me improvements if information is hard to find or obtuse.

[autoSteve]

That said, BJ, a wiki might be a convenient location to house FAQ, advanced options and contributing doco. These are monolithic documents that might be linked to from README.md, and you'd know what information you were after. Use Ctrl-F once in each wiki page.

I've not thought through the "cons" of doing so. Equally I kind-of see no upside to changing the status quo, which is of convention (apart from maybe advanced options). Just seems like change for the sake of change.

[gcoan]

Just to share another documentation example, Predbat documentation uses Github pages https://springfall2008.github.io/batpred/ with the 'make the docs' theme

This change was made a couple of years ago from what was a monolithic readme to separate docs per topic area. The documentation is searchable.

For Predbat it has been a good move, the project has grown substantially, there are now lots of devices support, a web interface, configuration options, etc. Having different pages gives some logical structure to setting up the config file, setting up from scratch, customising the configuration, viewing output data, etc.

For the Solcast integration you could split some of the readme up, as you have with advanced options, maybe separate page for initial setup, another for auto-dampening, but I'm not sure you'd see the same advantages, the project just doesn't have the same size nor complexity.
I personally don't see the point in separate readme's for different languages, browsers can do the native translation and you'd just causing ongoing maintenance.

[autoSteve]

Agree, Geoff.

I'm thinking of shaping tonights maintenance towards removing the translated README.md files.

They have not been updated for v4.5.0. I couldn't be arsed, and are out of date, so I guess there is our answer on that front.

It's that tonight, or watch a movie, enjoying the silence after ~3,400 downloads...

[BJReplay]

Happy to consider that approach.

But properly, tomorrow.

Big day water skiing today.

[autoSteve]

Like I said, if people are actually reading the readme but missing things because things are too hard to find then this is not a terrible suggestion.

If BJ enables the Wiki feature in the repo then you could make a start on a PR, @BDVGitHub.

It would provide a consolodated location for documentation, FAQ, and also AdvancedOption™️s.

Translated README.md would be dropped. Too hard, and Chrome with Google Translate does a decent enough job. GitLocalize for the strings only.

[BJReplay]

Wiki enabled. I've got other stuff to do, so won't be adding or moving content any time soon (today), but maybe later this week.

Currently limited to (and probably will remain limited to) contributors @gcoan @Nilogax @autoSteve

PRs considered, @BDVGitHub, but so far, I've seen discussions initiated, but no contributions.