I am building my brand new install of OpenHAB 2 (I am an OpenHAB newbie : ).
I am creating the documentation while I am progressing in my understanding of OpenHAB.
This is my first goal.
I do not measure how far this is from documenting the Demo as I do not know what is inside the Demo itself.
@kai:
have an issue with the documentation site. When I click on Getting started / openHAB basics or Getting started /Installing OpenHAB, the menu does not expand (as it does with the Documentation/Concepts menu items for instance). I cannot figure why. Can you help me ?
This is important. I am going to check this before publication.
This is a bit tricky - in order for the menu to expand, you already need to be on a sub-page (like Introduction->Items&Things).
See e.g. http://docs.openhab.org/features/addons.html, where it is NOT expanded, while on http://docs.openhab.org/features/bindings.html it is expanded. I think that should be improved in the menu logic itself, otherwise it is difficult to navigate down.
The best workaround for now is to always link to a subpage from a menu entry (i.e. âIntroductionâ links to the âWhat is openHAB?â).
Btw, I am planning a 2.0 beta3 for this weekend, so it would be cool to have some initial docs / getting started up by then!
The question here is, if it isnât much easier to âgetting startedâ from a working setup instead of creating everything from scratch. This was the idea of the demo package from the start (which exists since the beginning of openHAB 1 already). In order to activate the demo, all you have to do is to edit one line in conf/services/addons.cfg: Change
#package = standard
to
package = demo
I think even if the tutorial itself does not use the demo as a basis, the demo setup definitely needs to be mentioned and explained somewhere in the documentation.
The demo is a set of items, rules, sitemap, and persistence that implement a fully realized example configuration. The fact that it is a complete setup, includes examples of most of the sorts of things you would want to do with openHAB and is proven to work makes it an excellent and important resource for new comers to experiment with and build upon as they learn openHAB.
The installation and initial configuration instructions should include how to install and configure the Demo. A the later sections that talk about Things, Items, Rules, Sitemaps, etc. should use lines from the Demo as the examples as much as possible.
The opportunity here is to use the Demo to tie together all the different parts and pieces of documentation into a coherent narrative. The Demo is the thread that runs through all the parts of section 3 tying them together. For example, while reading about Things and Items I can reference the Things and Items in a complete working configuration and in a working context rather than in the abstract or in an isolated manner. It also allows us to bring in just enough from other sections when needed. For example, in the Things and Items section being able to reference Demo Items lets us point at a working Binding config and say âthis Item is bound to the Astro Binding, more info on Bindings are here, more info about Astro is hereâ. Then we can describe in the generic about the Binding config (and donât forget to mention that the binding is optional).
I think that being able to describe all of these parts of openHAB in a working context is a powerful teaching approach.
Furthermore it gives us as writers a concrete thing to discuss and describe. It is a lot easier to write about something concrete verses something abstract.
I have just finished the merge of what was already in the documentation repository and was I wrote last weeks.
The documentation (so far) is structured with way:
The site is working correctly on my computer.
I could do a PR now but I would prefer to do a last proof-reading of the text and checking of the links tomorrow in order to do a PR tomorrow evening.
@kai: does this fits with your plan ?
Sounds wonderful, thanks!
The PR is made.
Donât hesitate to post if any issue occurs. I will stay tuned.
Honestly, I am personally feeling a bit lost in the documentation.
I am clearly missing some âGetting startedâ - the user guide is a bit of a mixture between a tutorial and a reference guide. E.g. the most often section that people visit is the binding documentation. I had to search pretty long before I found that hidden in the user guide -> appendix -> add-on list -> bindings.
Also the âInstalling openHABâ is not really a suitable âgetting startedâ as it directly talks about tweaking the start script and changing the default port, stuff that usually should be avoided.
Things like the most important shell commands (which exist in the current install guide) are not mentioned anymore (but they are imho VERY important to know about for beginners).
I wonder if we should for a start reduce the number of books after all - rather have a âUser Manualâ and a âDeveloper Guideâ as the two entry points for our audience (especially as long as the Cookbook is empty and the Reference is almost empty).
Maybe @rlkoshak can comment as well. I actually also quite liked his suggested structure, which would fit nicely for the User Manual.
There are quite some "OpenHAB"s left in your PR 
I checked the and they are at the beginning of a sentence, so it sounds quite normal to have a âOâ.
Do you want me to suppress them ?
The users guide contains every thing that I needed to be able to do my first install.
It contains all the information needed to setup a first install, step by step, from my experience.
We can move it.
The fact is that I had to do it for my first install : it is the reason why it is there. It is an issue that the beginner will have. It must have the information at this point.
At the beginning of a sentence this is ok for me, but I also spotted some others. But never mind, I can also simply fix them myself whereever I come across them.
I have hardly ever heard about such a problem. I think it only applies to very few users, so I would rather consider this to be good for a âtroubleshootingâ section.
Please consider that the documentation as today is just the starting of an-going work the cookbook and the reference book will contains stuff coming from the wiki and the forums.
We could merge them in one book.
I have tried to improve the structure and the wording a bit and commented out the Reference and the Cookbook for now, so that the people only see the parts where there is at least some content. I created a PR against your PR with these updates: https://github.com/bipphilippe/openhab-docs/pull/1.
Thanks.
I will enhance the documentation next week in order to issue a new PR during the week.
What about the documentation (README.md) included in each OH2 binding ? Will it be automatically imported in the general documentation ?
Is there a template for this README.md file ?