Apply a consistent template to each, in the spirit of openhab2-addons.
Remove any OH1-runtime-specific information about the add-on.
Give a table of Binding Configuration parameters.
Remove information that duplicates already available information (like direct copies of xxx.cfg pasted into the markdown in the case that they are installed into the user’s services folder on install).
Fix differences between GFM and Jekyll.
Fold in directly relevant example wiki pages when it makes sense.
Monitor user edits to the add-on wiki pages (which I’ve already been doing with SourceTree) and adapt the README.md copies as needed. Hope and pray that wiki edits are few and far between until merge.
When merged, update the source wiki so it is clear which version of the documentation applies depending on runtime version. Do not delete information in the wiki that is still of value to openHAB 1 runtime users.
Small PR against openhab-docs
Update the build process to treat openhab1-addons as closely as possible to openhab2-addons, but using the master branch commit of openhab1-addons for the time being.
Remove links to the openhab1-addons wiki.
Concerns
A ridiculously long list of github users have edited these wiki pages over the years, and this would be a copying of their work and loss of the history of the page. Losing the IP record may be unacceptable. I could put a long list of Also-by: (github user: xxx) in the openhab1-addons commit, but tracking down their real names and email addresses is almost certainly infeasible.
This will wear out my laptop keyboard and what’s left of my vision.
Other concerns?
What do you think @Kai, @rlkoshak, @sihui, @ThomDietrich? Can this plan be improved upon, should I even begin, or would I be setting off in the wrong direction altogether?
Sounds like a pretty good idea to me - we can keep the old wiki for OH1 users in place, while adapting he README.mds to match the use within OH2.
As we do not have a clear IP records for the openhab1-addons repo anyhow, I don’t think that copying content from the wiki to the source repo is a problem. With the initial commit, we can refer to the commit id of the wiki repo to say that this is where it originated from. So there will still be a possibility to trace all history, even across the two repos.
I really like this idea. The more consistent we can be the better.
Is there a way to make the wiki read only while the transition is taking place? I think that is a small price to pay to limit the amount or rework that might be created while the docs are being transferred.
There are enough wiki pages, surely it would be worth while creating some sort of script to automate some or most of the transfer. At a minimum it seems like one should be able to convert between the two markdown formats.
I haven’t kept up with the Issues and PRs. If there isn’t already, there should be a tutorial on how to contribute to the docs once they have moved. In particular, for quick edits I had no idea I could do everything from within the browser and didn’t have to much with branches and such on my local clone of my fork.That removes a huge barrier to contributions for the less technically inclined as well as those of us who spend more time than not working through his phone.
Thanks! I will start with an initial PR, and add @sihui and any other takers as collaborators on it for the hand editing, dividing up by ranges of the alphabet. Hopefully it’s not too painful.
Maybe, but I will try to keep them in sync as long as possible otherwise. I do intend to automate some of it, but the tedious part is almost certainly manual because I believe a consistent style has to be applied to the existing content on a page-by-page basis.
Absolutely! Maybe a section added to “Contributing to the Development of openHAB” possibly renamed to “Contributing to openHAB”? The section could even be written now, since the same rules would apply to the other README.md files in the other repos already.
It’s about time we take care of that aspect and you have everything thought out perfectly!! I can’t think of anything to add. Let me know if any help is needed on docs side. Of course I can also help with the editing if it’s to much.
The intersection of the list of 1.x add-ons and wiki pages that document them will result in 188 new pages for docs.openhab.org:
Step 1 is to write a little script to copy them (in some cases concatenating more than one wiki page) into a README.md in each project folder, create a few model pages with a fixed style and layout (see OP), and solicit feedback with a work-in-progress PR.
I will certainly reach out if the editing of these 188 new README.md files is too crushing or moving too slowly.
To my documentation-minded friends, please have a quick look at https://github.com/openhab/openhab1-addons/pull/5029 to see if you spot anything I’m missing, like Jekyll markdown compatibility or anything else that will have to be redone. Many thanks.
Could you please submit pull requests to this branch, following the instructions in this pull request, and only changing the remaining files list here?
When all of those README.md files are correct, we will be very close to having the documentation for all 188 openHAB 1.x add-ons directly on docs.openhab.org, and we can leave the old wiki behind for all openHAB 2 users!
Un-wiki-fying all of the documentation will be a great step forward I think.
We don’t want to leave 1.x runtime users with no documentation, and we don’t want to pollute the gorgeous new docs.openhab.org with incorrect/outdated directions. We will certainly warn off openHAB 2 users from relying on the old wiki, but this effort will result in the removal of all links to the old wiki, and all openHAB documentation can finally live directly on docs.openhab.org where it belongs!
I can’t think of anything to add. Let me know if any help is needed on docs side. Of course I can also help with the editing if it’s to much.
