[WIP] Initial migration of doc contents to USAGE.md

openhab / openhab-vscode

VS Code extension for openHAB configuration files

https://marketplace.visualstudio.com/items?itemName=openhab.openhab

Eclipse Public License 2.0

159 stars 47 forks source link

[WIP] Initial migration of doc contents to USAGE.md #100

Closed Confectrician closed 5 years ago

Confectrician commented 6 years ago

CC: @kubawolanin and @ThomDietrich Ref: https://github.com/openhab/openhab-google-assistant/pull/40#issuecomment-397870346

Closes #93

This is the WIP migration PR for vscode, since we want to generalize the process of getting external documentation articles. I have started here, because we don't sync anything vscode related yet.

PLEASE NOTE This is just a raw cut, copy and past for now. Maybe this would be the right time to also make some improvements to usage and readme.

Goal

[x] Migrate to docs, docs/images and USAGE.md
[ ] Update and improve USAGE.md since we are touching it anyways now (suggestions welcome)
[ ] User README.md for repo and contribution information
[ ] Anything that i forgot now

Signed-off-by: Jerome Luckenbach github@luckenba.ch

Confectrician commented 6 years ago

@kubawolanin

My suggestion would be to clean up CONTRIBUTING a bit and move some technical/repo contents to readme. So we could split up the tech stuff and the legal guideline stuff nicely.

Also there was an attempt to share/sync the guidelines over all repos some time ago in an openhab-docs issue. There is not much progress currently, but we would be prepared for the future, if we store the stuff that is only related to vscode in the readme file.

wdyt?

Confectrician commented 6 years ago

Another question that has come to my mind:

Is the visual studio marketplace description served from the readme file on a fixed basis or could we configure to use usage.md while publishing?

kubawolanin commented 6 years ago

Is the visual studio marketplace description served from the readme file on a fixed basis or could we configure to use usage.md while publishing?

It's served from README file on strict basis so I'm afraid we cannot split it entirely. People are relying on the page both in Marketplace and Extensions page. So we'll need to be clever with choosing what to present there and what can be moved to the detailed doc page.

Confectrician commented 6 years ago

Or we have to replace the readme.md content while publishing a new release with a script or a similiar solution.

Most of the time readme and usage will be read here or in the docs.

Confectrician commented 6 years ago

I have thought about it several times now.

The case publish to marketplace is not as frequent as we are updating the usage or generate the website. Also we would have to make another exception in handling external docs for this repo. We already have many different ways of aquiring content for the documentation, which make it complicated.

My vote would be for:

readme es a repo information and contributors documentation
docs folder for user guidance and information
reference usage in readme
code some kind of script which generates a user friendly readme for the marketplace on the fly before or while the extension is beeing published.
maybe do some ci/build stuff for this in the future.

@ThomDietrich i would love to hear your opinion about it.

Confectrician commented 6 years ago

Reference #88. We should check for 3rd Party references, while updating the content.

Confectrician commented 5 years ago

To much changes meanwhile.

We have to update the readme anyway and then give it a clean try.