If you like I can make this a wiki so others can edit it. Though in practice few will and they will just post comments anyway.
Looks good so far!
Yes please Rich
I think at least Stefan will want to add stuff
Can you share the URL to the wiki?
It is the first post here…
I wasn’t aware that I can edit the post. Thanks #dummyme
As it was turned into a wiki post, you can
I started contributing and I wonder if the images should have an internal or external link, so we can later integrate this page into the official openhab documentation?
All the image links will need to be reworked no matter what you choose so I wouldn’t worry about it until it’s time to move them over to the docs. It would help though to save off the images somewhere with reasonable names because the images will need to be checked in along with the text as part of the PR. But the way the image tags work in the docs you’ll have to rework the links anyway so don’t worry too much about setting up something external for this post to host the images.
Ok, thanks for the info. Not really a good process unfortunately and not really temping to put many images in ( I will do anyway). Can we not push this page earlier to GitHub and then work on it there?
If you want you can create a WIP PR and work on it there.
However you’ll also have to run a separate service to build the pages so you can preview them as you write which involves a bit more work in the long run.
I’ve never tried to collaborate with more than one author on the same PR though so I don’t know how easy that is to do.
And you will pretty much cut off any chance of contributions or suggestions from the target audience. If they are coding in Blockly, they are almost certainly not going to be reviewing and contributing to a PR in progress on Github.
In my experience, the little bit of work at the end managing the images is less than the extra work required and some of the draw backs in terms of contributions and exposure to make it worth writing the first draft here on the forum and then moving them over.
I checked the Rules | openHAB in the repo which is at openhab-docs/rules-dsl.md at main · openhab/openhab-docs · GitHub and turns out to be a Markdown file, isn’t it? And it seems to have the picture referenced to the relative folder images. So it should be easy to clone the repo and write the md-file locally and see how it looks with an MD-Viewer. Does it come out quite differently after running the build or would that be worth trying?
Another question: Is there the possibility to have sub pages? I feel that the documentation will become quite comprehensive and long and would actually profit from being broken down in separate pages but I seems that openHAB Docs only has one level of page hierarchy, does it?
All the external references (such as for images or links to other pages) is not MD as far as I’m aware. There are some other small quirks that you probably won’t run into.
That never worked for me well enough to rely on it.
That’s a discussion for @Confectrician as the keeper of the overall structure of the docs for what is the best way. You can have subpages. Look at the UI Guide’s Component Reference page (which I believe is automatically built from the actual widgets and not from the MD files, but that would still work. Or you can have a sequence of pages similar to the Getting Started Tutorial which are all at the same level but grouped together on the left hand side.
I could see a single page with a generic “here is how to create a rule with Blockly” with a reference table that has links to a separate page, or parts of a separate page with the detailed info for that block.
As far as i know deeper hierarchies should be possible, but we only allow one level hierarchy in the sidebar navigation, so it does not get to overgrown.
So we could have a main page that would link down to the sub pages (which are not shown in the menu to the left), right?
Yes, this would be the current behavior.
We could for sure check, if we can define something different for blockly.
This should be a fair amount of research.
@ysc do you have something in mind about the navigation setting we configured in vuepress?
We can add a blockly section for testing purposes at any time.
Changes will only be available for the snapshot docs anyway until the next release of openHAB is published.
So we can’t destroy that much while testing things out.