Documenting openHAB 2

Well then make sure that is documented there.

1 Like

@rlkoshak Don’t think that I am not waiting anymore for your PRs, just because others are becoming active, too :innocent:

1 Like

I know I know. My wife is still in the cast until next week (I hope, it has already been extended two weeks) so almost all of my free time is spent picking up the slack. I feel terrible about my lack of productivity on this.

I am happy to see others are stepping up to write.

FYI: I have just commented out the “Advanced Tutorial” from the website as it is still empty/unusable and even the beginner tutorial is still almost completely lacking content. It is rather embarrassing to have t.b.d. pages all over the place, so NOT having the pages at all is imho the better option.

Once someone is willing to work on the tutorials, we can add it back at any time.

1 Like

Is someone currently working on the “Beginner Tutorial”? If not, happy to add some content.

1 Like

No, I don’t think anyone is - so yes, it would be great if you could add some content!

Hey Jörg,
I would suggest you create a github ticket “claiming” the beginners tutorial. Does everyone agree, doing that for all changes needed in the documentation will make working in docs a bit more transparent!?

Yes, although at the moment we rather have too few than too many concurrency issues. :wink:

1 Like

touché :sweat_smile:

At least the sitemap article is finished now :sleeping: PR and followup issue is ready.

@ThomDietrich, first I had the same idea but then I had same thought as Kai.

I think for the moment this thread is sufficient to align on the documentation. Happy to switch to a ticket mode once the masses of writers join us …:joy:

This may be. You should still claim the “beginner tutorial”. I was thinking about working on “items” next and have honestly no clue if anybody is working on that or would be especially interested in that topic.
We shouldn’t start to open 99 tickets for all the articles we can possibly think of, I’m on the same page with the two of you there :wink:

I would classify this as a css error. There is a rule section.text {overflow-x: scroll;} which produces this line and shouldn’t be there at all. I’ll have a look into that.

While I was setting up my OH2 system I started writing small notes to remember the exact steps I took to get specific things set up, but I wouldn’t by any means call them acceptable for documentation.

That being said, I’m keen to try and give something back to the OH devs and would be happy writing any documentation needed. My fear is that my abilities/understanding isn’t anywhere near comprehensive enough to really do a good job at it.

Is the process of writing documentation something that will get reviewed/tested before it gets put online?

Where is the best place to look for the sections which need attention?

I’d definitely like to have the 4-eyes-principle in place, so any PR should be reviewed by at least one other person. But at the moment, I prefer having content over making sure it is 100% accurate; it is much easier for people to fix errors in it than to come up with something in the first place. So any contribution from your side is very welcome and do not worry in case you are not sure whether you got it 100% correct (as long as you are open to feedback :-)).

Probably the doc itself, there are MANY pages that only have a “to be done…” entry.

Cheers,
Kai

OK, thanks. I didn’t realise I had to install Jekyll so will have to do that on my Macbook at home over the weekend.

Until I get that done, I’ll just start reorganising some stuff from my notes in Notepad++.

Most of my notes are copy/pastes from the forums and existing wiki pages, rewritten into sentences that make sense to me. And there are plenty of holes in my notes for some topics (persistence is something i’ve only barely scratched the surface of) so is there a preferred approach to indicate missing information eg [missing], [needs confirmation], (UNFINISHED) etc. ?

I see there was some discussion by @rlkoshak around the Table Of Contents, but this doesn’t match much of the work on the docs right now. Is there scope to work towards this with any notes I make? There’s not much point writing anything if it’s not appropriate for a section.

Hi @pahansen, when you look into the details you will find most of what @rlkoshak is there (beside that some of the headings changed and some minor changes to the structure).

Current the struture and status looks like:

  1. Tutorials - looks ok
    1.1 Demo Setup - looks ok
    1.2 Tutorial (Beginner)
    1.2.1 Overview - *in work by Joerg
    1.2.2 User interfaces - in work by Joerg
    1.2.3 Installing an Extension - in work by Joerg
    1.2.4 Working with Extensions - in work by Joerg
    1.2.5 Working with rules and script - in work by Joerg
    1.2.6 Looking at the Logs - in work by Joerg
    1.3 Migration from 1.x - looks ok
  2. User manual
    2.1 Concepts - looks ok
    2.2 Installation - looks ok
    2.3 Configuration - not much content, but what is there looks ok.
    2.3 Administration - looks ok
    2.4 Features
    2.4.1 Overview - empty
    2.4.2 Sitemaps - empty, but awating PR from Thomas
    2.4.3 Persistence - empty
    2.4.4 Automation (Rules) - looks ok
    2.5 Add-ons
    2.6 Appendix
    2.6.1 Downloads - looks ok
    2.6.2 Examples - empty
    2.6.3 Troubleshooting - not much content
    2.6.4. Contributing - looks ok

I think the general structure is ok for the moment. Of course there could be more polishing done, but getting rid of the empy page might be more important.

As you can see from above, most unfinished work is in chapter “2.4 Features” in which things&items, rules, persistence, … are described. So perhabs you want to start there?

Regarding change process: @ThomDietrich suggested to create a GitHub ticket to indicate that you work on a subject. Now that the editor community is growing, it seems to makes sense to start using it.

You don’t have to. You’ll write text in markdown syntax and a lot of editors, including the github online editor, support rendering a preview. As long as you use standard markdown elements (recommended anyway) and take other articles as an example, you should be fine.

If you still would like to check your work through Jekyll, you can use a virtual machine I just created yesterday: https://github.com/openhab/openhab-docs#alternative-vagrant-vm

My approach for missing information was, that the enduser should not be distracted by a bunch of “[missing]” in between. In my last article, I included <!-- Note to authors: ....--> comments and created an Issues ticket after the article was finished:

1 Like

Wow, OK.

I really have very little understanding of how markup works so will have to look into that. I also didn’t realise @luotaus had started some sections so I might just PM him what notes I had already written there and see if they’re of any use to him.

I’m not a guru with the persistence stuff, or trust my working enough to produce any examples for those sections.

I’ll have a look through each page and see if I can find anywhere else to add things, but my level of understanding of OH might reach its limit, heh.

My idea for chapter 1.2 (Beginner Tutorial) is to have a step-by-step guide for newbies which should help them to survive the first hour after installation. It shows the complete configuration workflow from installing a binding, adding things/items/rules to defining the UI. But it will focus more on the practical work and not so much on principals or concepts.

In my opinion, the basics like syntax, concepts, … should be handled in chapter 2.4. Based on Rich’s suggestion here I propose the following structure:

2.4 Features
2.4.1 Overview
2.4.2 GUI vs. Text Files Based Configuration
2.4.3 Things and Items
2.4.2 Sitemaps
2.4.3 Persistence
2.4.4 Automation (Rules)

While talking about the structure: I am not sure what to put into chapter 2.3 Configuration. I assume it was supposed as a sub-chapter of „2.2 Installation“ to describe backend configurations (like ports, ssl,… ) and by mistake moved one level. Or it was supposed to describe the overall configuration but then it would be in conflict with the current chapter „2.4 Features“. I think it makes sense to move the current „2.3 Configuration“ one level down below „2.2 Installation“.

And when changing the structure, I also propose to move chapter „Administration“ behind the config/feature chapters. So in summary, chapter 2 could have this high level structure:

2. User manual
2.1 Concepts
2.2 Installation 
2.3 Features
2.4 Administration
2.5 Add-ons
2.6 Appendix

What do you think?