On the importance of Persistence in the Documents

@kai, @ThomDietrich,

Continuing the discussion from here about whether Persistence should be listed at the end to bring Rules up in the list.

I think the summary arguments are:

  • users want to get to Rules as soon as possible so that section should be closer to the to top
  • persistence is often overlooked and ignored but a key and important capability, and it is one piece of foundational information to fully understand rules

I think persistence is a function not all users will use. In your scenario: “Once you have Items you can create a Sitemap. Oops, what happens when I restart? Don’t care because the device is on 24/7, that’s a problem that I can think of later. More importantly, let’s finally have a smart smarthouse! rules! rules! rules! … Almost finished? Well now that I think of it, it would be nice to have a chart with the temperatures in my sitemap.” That’s what I think can be compared with most other documentations where things like Backup&Restore or Troubleshooting are at the end of the documentation, even though a user might want to look into them sooner.

My position is that persistence is a function that all users should use, at least until such time that they have enough knowledge and experience to actually make the decision to use it or not. I’ve helped far too many people on the forum who are frustrated primarily from an ignorance about what persistence does. In my perfect world, OH would come with a MapDB restoreOnStartup for all Items persistence configuration on by default. Short of that, placing Persistence above Rules in the table of contents is a way to stress its importance.

The entire documents are hypertext, not a physical book, so users who jump to the conclusion that they don’t need persistence will still jump ahead.

Maybe the reason a lot of users (can’t speak from personal experience) didn’t know about the possibilities of persistence should be tackled by giving the menu entry a better (less technical) name and by having a nice short configuration base article explaining in a few bullet points what is possible connected with links to the in-detail articles.

I agree, many of the section titles need to be reworked and Persistence is not necessarily as meaningful as Rules may be. However, “Persistence” is the technical term for the capability in OH and I don’t want to have to talk around it. Perhaps subtitles to the sections would help:

  • Things and Items: Representing the Real World in openHAB
  • Sitemaps: The User Interface to your Home Automation
  • Persistence: Saving and Accessing Historic Data
  • Rules and Scripts: Defining Home Automation Behaviors

having a nice short configuration base article explaining in a few bullet points what is possible connected with links to the in-detail articles.

This sounds like a good organizational approach across the board. A brief intro paragraph describing what the capability is for, how to configure it, and links to articles that delve into the details.


Hey Rich,
I have not much to add, that’s a pretty convincing reasoning.

Yeah sure, nice idea! Would you like to add this to the demo configuration?

Nice. This should be part of the base article. Would be amazing to have a block diagram similar to the one over here in there too.

Actually I think @kai is waiting for a PR on ESH related to Persistence that it looks like @chris is working on to implement this. At least to implement it as the default for OH. But it doesn’t hurt to add it to the demo now I suspect.

Where is the demo these days? I presume it isn’t part of the Documentation repo. Maybe it should be? Particularly if my vision of having the Beginner’s Tutorial be so closely tied to it. I’m not sure the infrastructure is in place to support that yet though.

I like drawings. Maybe come up with one drawing showing how all these parts logically work together and a way to highlight which block is bing talked about in each section. Kind of a “You are Here” for the visual learners out there.


Drawings are gold. There is a german saying, probably it’s the same in english: “A picture tells more than one thousand words”. Hey you wanna see the - in my eyes - by far best documentation for a software out there? :slight_smile: https://www.softether.org

One question:
“Maybe you can come up” or “Maybe I’ll come up” ? :smile: I’m voting for “Maybe someone can come up”

all similar software of openhab have an integrated persistence always active. Maybe after you can change with mysql or other, but at begin a raw data file active is enough.