Hello everyone,
the more I read in the OpenHab and Eclipse SmartHome documentation, the more I notice, that the provided information is inconsistent. For example the IDE setup of OpenHab mentioned you should not use spaces in the install path on windows, whereas the IDE setup documention of Eclipse SmartHome did not. This has proven an issue, since I know of at least to people (me included) that read the Eclipse SmartHome documentation and failed to create the path without spaces.
So my question is: Is there any good reason, why so much information is documented twice? Why does the Openhab documentation not link to the Eclipse SmartHome documentation, or the other way round, instead of explaining things twice?
If this has to be done manually I think it is really prone to error. Or does anything exist that makes sure the provided information on both pages is the same?
This is just something I noticed and I’d really like to know your thoughts about that
I guess that’s not by intention. It’s an OH principle to de-duplicate as much as possible and applies to the docs, too.
It’s probably a leftover from the split of OH1 into ESH and OH2 [well that description isn’t 100% accurate but reasonable I guess] that simply noone has spotted and corrected so far.
If you spot inconsistencies or errors in the docs please open a Github issue against the docs (there should be a link at the bottom of each page to help you with that).
PS: and who the heck is still using spaces in path- or filenames ? It’s basic knowledge that that’s a bad idea.
Sure, but that still does not account to the problem, that the files representing documentation of the same topic are present in two repositories. So that would mean in order to keep the documentation consistent you’d always have to change the file in both repositories manually, which you might or might not forget.
Alright, will do
I think I will just create two issues for every topic I edit and ask if one of these can be deleted before I start. It’ll be a hell lot of work to synchronize the documentation though.
This is one topic that I have discussed with some people at the last smarthome day.
I agree totally with this especially for the development docs.
Unfortunately I had not yet enough time to push this topic forward, but it’s definitely one of my prio topics for the documentation.
So @mstormi is right.
Open issues, be part of discussions and hopefully we can find a valuable solution for improving this in the nearer future.
Some general information aside:
We are already building parts of the openHAB documentation automated through our website generation.
That means that not all articles have to be maintained in both repos.
The currently up to date version gets copied from the eclipse smarthome repo at the time of website generation.
The substantial problem is that there is no demarcation criteria between those documentations. Neither the ESH nor the openHAB community/maintainers did define which information should be part of the docs and which shouldn’t.
For example, the ESH documentation does hardly contain any information how to use the runtime as a user, it focuses more on technical information for developers that want to integrate the framework. Anyhow, I think currently for an ESH “newbie” developer it’ll be hard to understand ESH without also reading the user documentation of openHAB. Even the ESH Getting Started Page recommends software developers to start with openHAB 2: "How to start: Take a jump start with the distribution of openHAB 2 to get a working solution with Eclipse SmartHome™".
Before we do anything, we have to create some common understanding and a detailed guide for users, contributors and maintainers into which documentation we put which information about openHAB / ESH.
Ok, I’ll do that! I’ve spent a lot of time reading the documentation, so I might as well improve it where necessary
Thats a good idea! Which part of the documentation is automatically generated? Could you point me in the right direction on how this is done?
Yes, I think there should be some better distinction between the two projects. Maybe some kind of documentation would be necessary for that as well. It could start at what code is contained in which project, then provide information on which topics are documented in these projects, and I think it would be useful to also provide information on where certain topics are discussed. I am not sure if the same people read this forum and the one of Eclipse SmartHome, so I’m sometimes confused about where I should ask which question.
Being relatively new to both OpenHab and Eclipse SmartHome I am not sure if I can be of any help with these matters though. I feel like demarcation criteria should be defined by someone that has more experience in both projects.
