Pimatic documentation

---

One of the problems for new users is the lack of solid documentation. The core users that has been with pimatic for a long time now what is possible and what not, but even theses users sometimes have to scratch there head figuring out how something is done.
So, how can the communicty help writing documentation? I’m willing to contribute and write some stuff, but it has to be something can be done by everyone wiki-like) so it’s not a one man show.
Also some structure in the documentation would be useful.

Who wants to help, and how can this be done in a way the forum (and users) benefit of this information.
@leader21 any idea?

Love the idea!

However if we want to do this right we need to have a very easy way to contribute. The “old” Wikis in my experience are to cumbersome to use.

@sweetpi Isn’t a big part of the documentation generated? --> Should be possible to be extended via git and pull-requests.

But this is even more complex than the old WIKIs

In order to solve this we would need a way everybody even without technical knowledge can contribute to this.
Ideas?

• Maybe a clearly visible, easy to use, “how can we improve this documentation” box on the bottom of each documentation page?
• This way someone with the knowledge how to update the documentation could quickly improve the documentation with some copy/paste.

The hurdle really has to be very low if we want feedback from not so technically avid users.

Thank you very much for taking the initiative on this. Much appreciated! I agree the documentation should be improved to aid new users, in particular. I agree the lack of solid documentation is one of the major short-comings.

One source of documentation is the pimatic-guide project where everybody is invited to contribute - https://github.com/pimatic/pimatic-guide. The project is written in Markup-Style which is fairly easy to learn and also suitable for users who are not familiar with programming stuff. Contributions can be made via pull requests - which is easy, but obviously needs some explanation for users not familiar with github. Alternatively, user can simply post their contributions on Forum or create an issue on github.

API-documentation is generated from source and I strongly believe this is the way to go. Other projects which used Wikis for that are now switching back to documentation generated from source as the Wiki stuff ended up in a complete mess. A popular example for that is the J5 project.

For any outher documentation like Trouble Shooting, How-Tos, and such, I think a Wiki would be really helpful and serve better than forum posts. I think it is very easy to run Wikis as part of github projects and it is also possible to render them into a web site similar to what we have for pimatic-guide.

We’ll discuss the matter and get back to you shortly.

well, the forum has been a fast solution to create some kind of support and trouble shooting once it has started. within the past two years the forum grew to a large book of reference.
there are many many information on almost everything that pimatic has to offer. the search can be troublesome as you may drown in possible threads. pimatic “nerds” already know what to search for or just post a quick help question, indeed. but not all users dare to ask and rather read.

the main documentation is created out of the pimatic-guide as marcus said above.
as long as we are not having any other possibility, you are all invited to participate of course

we are discussing this internally hoping we can come up with a solution that fits our needs.
stay tuned

Sure the forum is a treasure trove of information. However when I introduced some friends to Pimatic I had to learn that you can’t even search the forum if you are not registered which is a hurdle for the people who don’t want to create yet an other account.

@thex you are right! the search has been disabled for guests by default.
i didn’t realize that until now. changed it, so everybody is able to search the forum!

@leader21 I think the search function should be kept exclusive for registered users for good reasons. Many forums do that to avoid overuse and misuse of the system by bot software.

A sort of compromise is to ask unregistered users to enter a captcha with each search action, like it it is done with FHEM forum, the KNX User Forum, or IP Phone Forum, just to give a few example here.

captcha would be a good compromise, I think requiring registration is to restrictive

Following earlier requests for better documentation and for collaborative tools to allow users for contributing to the documentation, a Wiki has been setup. The new Wiki already contains a major part of the pimatic-guide. The Wiki is kindly provided by Teamemo, a company which has been co-founded by @sweetpi.

While the former “pimatic-guide” required basic knowledge of “Markdown” and how to use “Git” and “Github”, the new Wiki provides an easy to use Wysiwyg Editor.

Anyone interested in in contributing to the documentation is welcome!
Please get in touch with @leader21

@mwittig
@leader21
Is it posible to give a link to the wiki direkly from the forum?
I don’t find one, only on the pimatic.org page. That makes it a lot easyer to find it.

@V1per said in Pimatic documentation:

Is it posible to give a link to the wiki direkly from the forum?
I don’t find one, only on the pimatic.org page. That makes it a lot easyer to find it.

Sure. https://pimatic.teamemo.com/

@mwittig
You shows the pimatic.org side, there I have found the Link.
I mean here in the forum maybee on the top where the guidelines and the howto are linked.