Parting thoughts on the documentation

Hi folks! I’ve spent a couple of weeks here trying to use EmonCMS as a visualization tool for historic and live meter data for electrical, gas, and water consumption and demand. I’ve dropped a couple of posts in other categories as seemed appropriate, but I thought I’d try to describe my experience of the documentation as a new-but-technical user.

FAQ: So awesome that you’ve got one and that it’s relatively visible now. It… didn’t have any of my EmonCMS-specific questions in it, though. Perhaps it would be better if there was a separate FAQ stickied in each category.

EmonCMS-specific documentation: All of the beginner documentation seems to be aimed at someone using an OpenEnergyMonitor package. More and more people are going to be bringing their own data, as the utilities start to open it up to them. I’d suggest you be open to a cohort of new users who are only interested in learning to use EmonCMS. If they use the software first, they may come to buy the hardware later.

EmonCMS vs It’s not clear if they’ve got different functionality, but is the entry point for most people, and it doesn’t even have a version number on it. How can you tell if a bug is specific to the .org website, or if it still appears in the bleeding edge v9 software in github? If .org is a branch of what’s in github, please make it obvious, particularly in the github issues page!

EmonCMS Terminology guide: You invented a lot of terms for EmonCMS, and it was really difficult to wrap my head around what things meant and how the parts fit together. I posted the beginning of a terminology guide in the Getting Started category, but really it should be part of the beginner guide to EmonCMS.

Old Forum: I’m ashamed to admit how long it took me to figure out that the old forum is dead. But that’s the one that comes up when you google “EmonCMS forum”. Can’t you sticky a post linking to the new one? Or change the “forum” link at the top to go to the new community?

Feed recipies: It’s really hard to learn how to create meaningful feeds for visualization. The fact that you can’t see the result of your change until the next data comes in makes it very slow.
The beginner docs would benefit from a page of commonly used feed recipes with their intent and results.

Attitude: I saw a lot of answers in the forums that said “your question is answered in such-and-such a place.” It may be true, but you could serve future people with the same question very well by just providing a link to the document that they ought to read. If you don’t want the forums cluttered with newbie questions, consider moving them to a Q&A site, or at least just giving them their own category. I don’t know if Stack Exchange Electrical Engineering would accept it, but there are lots of Q&A-centric alternatives.


Hi @thundersun

Thanks so much for taking the time to write down your Getting Started with Emoncms experience. You have raised a number of important points that we will get look at making improvements.

It’s true the recent documentation overhaul has been focused on users using our full system (hardware + software). We will look at improving the specific Emoncms documentation.

Cheers Glyn, great project, and a great community. I wish I could contribute more than my notes. I look forward to another project in in a less-crazy future that is a better fit with OpenEmon!

1 Like