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 
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. 
1 Like
touchƩ 
At least the sitemap article is finished now 
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 ā¦
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
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:
- 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 - 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: GitHub - openhab/openhab-docs: This repository contains the documentation for openHAB.
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?