Well I clearly didn’t go back on the blog far enough. Thanks for the link. So basically ESH is much (but not all) of what we would call “core” on OH 1. And while ESH implements a lot of capabilities, by itself it doesn’t really do anything. OH 2 is an application built on top of ESH.
So any OH 2 developer documentation will really just need to discuss additions and modifications OH 2 makes to ESH. And even then only those additions and modifications that impacts a developer needs to be documented there.The user facing stuff would be documented in the user’s guide/tutorial.
I like it. I would suggest that focus be initially placed on bulleted points in a tree like structure. We can then build out the sections and points over time and provide more detail, context, etc., as well as periodically change the structure as feedback is integrated.
Ok, so we all agree that we like it - now it only must be done
With more on more functionality being added to OH2, I think it is now really time to get some better documentation out of the door (and to aggregate it to a single place).
Is any of you volunteering to work on the infrastructure? I don’t think that we need a Jekyll expert for it and we probably can re-use a lot from ESH. It would be gorgeous, if one of you could take the lead on this!
I so desperately want to take the lead on this but realistically, if I did, I would not be able to keep up with any sort release deadline. It would be far better if someone who can devote the time necessary to devote to it would take the lead. This isn’t something I can do from my phone during five minute breaks throughout the day which is how the vast majority of my postings to this forum have been made (sorry for the bad grammar and weird word substitutions).
However, if no one steps up, I will do what I can. It just won’t be fast. Jekyll does indeed look to be pretty easy to work with, particularly if you are used to a SW dev workflow.
I am also not able to keep up with any deadline and therefore we hardly ever set any deadlines -
I prefer to have things moving forward instead of creating schedules, which then cannot be met because nobody eventually does the work. Hence moving slowly is definitely better than stagnacy!
But let’s give the others a chance to step up - if they don’t, you have the job
I think from the time I have known you in this forum you would simply be the best for this task … the explanations you are giving in your posts are always extremely valuable and even more important: everybody is able to understand what you mean
So if you see a chance to spend your spare time for this: I will vote for you!
Note that the discussion is currently not about the content, but the technical infrastructure, which indeed cannot be done in 5minute breaks on a phone… I agree with you that @rikoshak is actually the better fit for working on the documentation content.
I didn’t mean to say that you are lacking the skills for the technical parts! Just wanted to express how important you will be for the content side of things afterwards as well
I thought we were still in the “waiting for somebody else to step up” phase
So I would say: You have the job, @rlkoshak - congratulations !
Start whenever you feel ready for it - and let me know whenever you have questions.
@rlkoshak I hope your family is feeling better again.
Do you already see and light at the end of the tunnel and could give us an estimate on when you might be able to start on this topic? I think having a structured documentation for openHAB 2 becomes more and more important.
Thank you. The family is indeed feeling much better. I do see a light at the end of the tunnel but that light is still at least a week off unfortunately. My plan is to start working on this in the evenings starting this week. But, given I haven’t even started yet I’m not sure how long it will take. I’m hopeful it won’t take long and I’ll be able to mainly lift ESH’s and do minor mods to make it appropriate for OH 2.
BTW, to show how truly behind I am on this, what is the target repo for these docs? openhab/openhab-distro, kaikreuzer/openhab-core, https://github.com/openhab/openhab2-addons? Or is it all of the above? I can see good arguments for any or all of them.
As already stated above, I think the source of the documentation should be close to the code itself - so it will be distributed.
General documentation on getting started, tutorials, etc. should imho be in openhab-distro, where it is already now. This should also be the central place to define the structure of the documentation and do the assembly of the different parts - it would be best, if Jenkins could directly commit any new version to https://github.com/openhab/openhab.github.io, which is the repo from which our website is served.
Understood. I have cloned the repos and run jykell to create a base jykell project for the docs and have been trying to setup the maven builds to work like those in ESH. But I haven’t got very far and it is difficult to make much progress without spending large chunks of time in one sitting.
It looks like I’m going to be snowed in this weekend and my plan is to spend a couple of hours on this tonight, Sat. and Sunday.
However, if anyone is able to spend more time on this in the short term than I can I am more than willing to give it up to someone who can be more productive.
!