Thanks @rlkoshak to get that started!
I also do not yet have a clear opinion on how the documentation should be handle best, but let me give you some facts:
- On github the main entry point is moved from openhab/openhab to openhab/openhab-distro. openhab/openhab already now only contains the add-ons and the wiki is only kept as “legacy” documentation for the (currently still official) 1.x runtime.
- On the “why to move”: Because 2.0 will simply be the next runtime release, there won’t be any 1.9. So the answer is the same on why people should move from 1.7 to 1.8: They don’t have to, but if they want new features and fixes, it is the only option. @rlkoshak and @danielwalters86 are right: You can continue using your 2.0 runtime exactly the same way as the 1.8 - you can keep your existing config files and you might only require minor adoptions. I had already started a page to keep track of such changes. After all, the MAIN change of 2.0 over 1.8 is that the codebase as moved to Eclipse and thus the namespace of the classes has changed. So it is really only an evolution and no revolution. The situation that there are problems with certain add-ons is mainly due to the disconnection of the 1.x maintainers with the changes in the runtime in the past two (!) years - this is what I am now trying to force with discontinuation of the 1.x runtime, so that required fixes are eventually done on the 1.x add-ons.
- Back to the documentation: I agree that a split in tutorial / user reference / developer guide make sense. One thing to consider is that the code is distributed and thus will be the “sources” of the documentation. E.g. the documentation of the different add-ons is directly included within the bundles (see where the links go on this page). I introduced it this way because it has several advantages: The documentation is versioned together with the add-ons, i.e. a PR should always also directly contain the corresponding documentation changes. With the current wiki, this is out of sync and we do not have the chance to look up the documentation of a binding for an older release, which is bad.
- Tutorial: This is something that already exists in a German version for openHAB 1, done using ReadTheDocs. I am not sure though, if we should rely on another 3rd-party service for this. I would actually prefer to have it auto generated through Jekyll and deployed it directly to the openhab.org website (which is also fed from a github repo). Some content for the tutorial is also likely to come from ESH (like e.g. some concepts), so we should make sure that we do not have to maintain to many things twice, but rather do “single sourcing”.
- User reference: This will be specifically the aggregation of the add-on documentation from the different repos, so again, I think this must be an automated scripting and generation through Jekyll like the tutorial.
- Developer docs: 90% of the content is likely to be identical to the ESH docs, so the content should imho be maintained at ESH. To adapt it (e.g. show another IDE setup page) and have it in the openHAB “style”, it again would make most sense to have an automatic script assembling the content and use Jekyll to do the proper HTML rendering.
Note that all this infrastructure has already been built for Eclipse SmartHome - it can be found in https://github.com/eclipse/smarthome/tree/master/docs. When running a Maven build within this folder, the documentation sources are assembled and Jekyll is called to use an HTML template for producing the website, which is then available at https://www.eclipse.org/smarthome/documentation/. I think it would make a lot of sense to use this infrastructure for openHAB as well (which was a goal when creating it for Eclipse SmartHome anyhow).
Regards,
Kai