EventGhost

Posted: **Fri Jun 09, 2017 10:33 pm**

The benefit of having documentation content in the EventGhost repository and built in to the application is that this will provide a snapshot of the documentation that matches the EventGhost version being used. As the application changes the documentation should change along with it. If you go to a system of only online documentation then you have two options:

Show the user the documentation for the latest release. If they're using an older EG version then the online documentation is ahead of their version. If they're using a pre-release then the online documentation is behind their version because the online documentation only gets updated during a real release.
Version-specific online documentation. You could publish a copy of the documentation for each release. e.g. http://www.eventghost.net/docs/0.5.0/ and link to the appropriate version from the application Help menu.

I don't see any benefit from generating wiki content from the documentation files in the EventGhost repository. We would need to make those wiki pages protected from edits because otherwise any edits someone makes to those files would be lost as they are overwritten on each release. The whole point of a wiki is for it to be editable. We already have a system for publishing online documentation so putting a lot of work into creating a new system that provides no benefits seems pointless.

As for changing to a system where the documentation is updated by editing the wiki, that is more appealing. The downside is that with the current system if I submit a pull request to add a new feature I can include the necessary changes to the documentation update with that pull request in the same commit as the change. The changes to the documentation can be reviewed as part of the pull request. The documentation is automatically updated when the pull request is merged. If I had to wait until the pull request is merged before updating the wiki it's much less likely for this to actually happen.

I do like the idea of making it easy for anyone to update the documentation but with the current system of having to apply to join the wiki usergroup and then wait to be approved it's actually not significantly easier than submitting an issue report or pull request to the GitHub repository.

It seems best to me to stick with the current separation of documentation and wiki and in fact to create a sharper divide between the two. It has long been a source of frustration to me that the two have bled into each other to such a ridiculous level. The documentation pages should be limited to things that are tightly coupled to the source code such as the command line options. The wiki can be a place for people to freely publish information that is more random in nature, such as a tutorial on how to control a specific device with EventGhost. The documentation content should be very tightly controlled, the wiki content should be given more freedom.

Posted: **Sat Jun 10, 2017 1:41 am**

OK so what you are saying is pretty much that the media wiki is for plugin documentation and core documentation stays with the core

Posted: **Sat Jun 10, 2017 2:11 am**

More like the wiki is for "everything else". For example, the "User Contributed Configs". Perfect use of the wiki but it would be a terrible idea to put that in the documentation.

Another example is this "Controlling your living room with EventGhost" thing. I have no problem with that being in the wiki but it's just insane to include it in the documentation.

Posted: **Sat Jun 10, 2017 2:25 am**

ok so if it is not core related then it should be in the wiki. I would also like to do something for the programming end of things. more techy information about the function/classes/methods of eventghost. this would also house the information on how to make a plugin.

and leave the builtin docs for things like command line parameters. the various options in EG and what they do. basic macro creation.. things of that nature. I do think the core plugins documentation should be in the builtin docs. these plugins are System, Window, Mouse, and EventGhost.

what are your thoughts on that?

Posted: **Sat Jun 10, 2017 6:01 am**

I agree that the documentation would be the appropriate place for the core plugins documentation.

Here's my thoughts on the current documentation pages:

Controlling your living room with EventGhost - Should be in the wiki. A duplicate page has always been in the wiki and I have submitted a PR to remove it from the documentation.
Short Manual - Should be in the documentation.
Features - There's not enough content here to be worth its own page. It could be expanded a little into a "What is EventGhost?" page.
Supported Remote Receivers - I think this page would be more appropriate for the wiki. Support for some remote receivers may be added by 3rd party plugins and the plan is to move the plugins out of the EventGhost repository so this information is not directly related to the EventGhost application.
List of Plugins - I believe this page is automatically generated because I don't see it in the repository. I think it would make more sense to have a single plugins list, either a wiki page or some sort of a plugin repository. Once the plugins are moved out of the EventGhost repository this page will be obsolete.
Scripting with Python - I think this content is appropriate for the documentation but it seems to have a lot of overlap with the "The eg module" documentation page.
FAQ - Not much content there. As it is now it seems to be more appropriate for the wiki but if the content was different it could go the other way.
Command Line Options - Definitely documenatation
Contributing - Seems appropriate for the documentation
Changelog - Documentation, but I notice it hasn't been updated since 2009!!!
Developer documentation - These all seem reasonable for documentation

kgschlosser wrote: I personally would like to see a page in the media wiki that would list the EG versions with all the changelog information for each version on it.

There is already a changelog page in the documentation: http://www.eventghost.net/docs/changelog.html

kgschlosser wrote: if for some crazy reason github goes belly up tomorrow and they shutdown all of the servers that information is lost. if it is stored on a server we control and have the ability to make backups of the database all is not lost.

I agree that we should not absolutely rely on GitHub. All data in the GitHub repository should absolutely be backed up automatically regularly. It's not just about them "going belly up", it's possible they could have some sort of glitch or hack that causes permanent data loss. There are two types of data stored on GitHub:

1. Git repository - This can be backed up by simply running the command:

Code: Select all

git clone https://github.com/EventGhost/EventGhost.git

That will back up the entire commit history.

2. GitHub data - The EventGhost repository contains other valuable information that is not included in the Git repository because they are from features that are GitHub specific:
- Pull Requests, and their associated reviews, comments, labels, and references
- Issues and their associated comments, labels, and references
- Commit comments
- Releases (tags are part of the Git repository but the release notes are not
This can all be backed up using 3rd party tools or the GitHub API: https://help.github.com/articles/backin ... epository/

kgschlosser wrote: if it is stored on a server we control and have the ability to make backups of the database all is not lost. i wish there was a way to have github or an extension of it run on our own systems and store all of the relevant information on our systems instead of on their servers. I know we can run an svn server but I think that would be going backwards in a sense compared to github. I simply do not like having to rely on other companies for things. they could at some point all of a sudden want to start charging people for public repos. and then a scramble takes place to move the content elsewhere. it's a pain to do that and it's worse when there is a time frame you have to do it in. we have all seen this kind of thing to many times. and out time is worth a whole lot and would rather not see us have to use it because of some knuckleheads decision.

Your argument does have some historical evidence on its side. SourceForge used to be the hot thing, then they started running malicious "download link" ads, distributing adware with people's code, and taking over popular projects after the owner deleted the project and moved it elsewhere. So people moved to Google Code, then Google shut that down. However, I think GitHub has a lot more going for it than either of those options. I don't see it going anywhere or turning evil. At worst we would see some unobtrusive advertising and more strict bandwidth limits on free repositories, which would be fine. If GitHub ever did shut down or turn crappy I think there would be new services that would allow you to migrate seamlessly by just clicking a button. SourceForge is still going. Google Code shut down but they provided an automated system for migrating to GitHub and they still maintain read-only archives of all the content. There is software such as GitLab available for you to run a Git host with "social coding" features similar to GitHub but that will just use bandwidth, increase the maintenance load of this website, and make the project less accessible to contributors. We're running a 7 year old version of MediaWiki that didn't even work for at least 5 of those 7 years, I don't see that it's a good idea to add any more complications when GitHub does an excellent job of this for free. Just look at all the bigtime software projects that are hosted on GitHub! There is a much higher chance of that software "going belly up" than there is of it happening to GitHub.

Posted: **Sat Jun 10, 2017 7:30 am**

I am just using what has happened in the past with other code management sites. As long as there is a means to get all of the data from GitHub this needs to be done on a regular basis. that is/was my biggest concern.

and my question for the developer tools as such I don't think is a necessity to be in the documentation. there should be a Wiki page for this. The reason why is. when we start actually adding to it it is going to really bloat the help files with information that most users will not even use. And it is a whole heap load of information that is going to be added. Now if we simply start another Wiki page for developers and keep is separate from the "users Wiki or keep it in the documentation is what i would like to know your thoughts on. The reason why is I have already started setting up a test server and documenting the process. this way it will hopefully be seamless and if i need to get a second instance of Media Wiki up and running now would be a good time for me to work those kinks out on the test platform.

Posted: **Sat Jun 10, 2017 8:09 am**

The GitHub wiki could be used for that purpose.

You could also just have a subpage of the documentation pages to list the developer documentation pages with a note explaining that this is advanced information.

If that information is kept somewhere separate then there should definitely be a link to it added to the documentation.

Posted: **Sat Jun 10, 2017 3:31 pm**

that is a fantastic idea!

Posted: **Sun Jun 11, 2017 8:29 am**

From all the above here is how i would summarize it:

offline help file
User documentation for cli args, main plugins, usage and links to 3+4
eventghost.net/documentation
same as 1 but online
eventghost.net/wiki
Additional info (by users) with examples, supported devices, etc. and link to 2+4
github.com/wiki
Infos for (plugin) developers and link to 2+3

1, 2 and 4 are maintained from (github) repository and 2 is maintained from forum users.

Did i get it right?

Posted: **Sun Jun 11, 2017 9:17 am**

Posted: **Sun Jun 11, 2017 5:41 pm**

from what i have seen an optimal document layout should be as follows

eventghost.net/docs

and/or

docs.eventghost.net

either one would work. or both at the same time makes no matter. but i am going to use eventghost.net/docs for this example because this would actually be it's physical location

eventghost.net/docs/en/0.5/help
eventghost.net/docs/en/0.5/userwiki
eventghost.net/docs/en/0.5/codewiki

as far as the help goes. one of the following should happen either we deep six the offline help and go with an online one. and when help is clicked in the program then it would load up an IE window or launch the browser and set the address to the online help. or we bundle that help with EG and do not have the online variant.

The big reason why i like the online variant is if there is a change that needs to be made to the help then a new release does not have to be issued for it. an updated version would be fixed but also someone can manually go in and make the changes to the help which will populate the help for the current release and anyone that uses it would have the most up to date help for that specific version without the need to install a new version. now we could still compile the help files and store them on the server and if the user wishes they could be given the option to download the offline help files if they want. that is a possible solution to that.

the code wiki would be a simple pointer to the github wiki as i do think this would be the best place for the plugin creation and scripting docs for EG only because it is really geared to that sort of thing.

and the user wiki is just that. Now as far as the code and github wikis go there could be a standard set that would be used as a template to populate the various releases and if something is incorrect for a specific version then changes made would only affect the wiki information for that specific version. if a wiki is created that pertains to all versions of eg. then the admin could at that point add it to the template. This would prevent contamination between versions and allow for things to be version specific if needed.

And not all of us do speak english. so anyone that wanted to spearhead translating or adding information in another language would be able to do this. now i do know that this is kind of an odd duck from a management stand point. because any of the core coders will need to have global write access to the docs. user/code/help but we need to keep things correct and there should be only one "head" of the user/code/help as pearbear does have a good knowledge of programming and an excellent knowledge of documentation I would still like to see him take on this challenge. and @dequi would be his backup. but for the love of god never go simply changing things without mentioning it it has to be brought up. to many things could get broken and or data destroyed this is another reason as to why I want to do a VPS is because there would be a build website to test everything against before a release gets issued so we do not break anything.

the code wiki would be largely populated from the builder and the help would be as well but not from the use of docstrings in the code. the help files to be built would be separate files as not to congest the code and these things will not need to be edited all the time so changing them could be less convenient to do.

@dequi I would really really really love it if you would help me with the server change. you seem to have knowledge of PHP which is something I do not have and would have to learn as i go. I would much rather have a mentor on this for that end of things. The initial setting up of the server is not an issue for me have done it many many times but anything we want to add/changed in the code is where i would need the help. and I would also love it if you would continue with the plugin manager on the website ends of things and setting up the backend of the repository on the server. this would require a meeting of the minds so to speak on all fronts because something like that is going to affect the code/website/docs. this can wait until after the server move but organization of the plugins can continue while this is taking place. I am more then happy to work on organizing the plugins as well. would be cool if everyone pitched in on that end of things.

I know that @topik2k has been overwhelmed with real life work. and I do know this happens to all of us. and we do not want to intrude on that. everyone has a life beyond EG and has families to take care of and moneys to be made. So if you need to slow down with work on EG then simply let us know. this way we don't want to bother ya. Family and providing for them is always first and foremost and I think that we can all agree on that. life will go on in EG land and you will not be left behind. What would also help is if you possibly left one person in charge of communication with ya. this way you know that if that person asks something it is going to be something important so you won't get beat up with menial things.

I think we have a really good solid team starting to form here we have the right people with the right knowledge to get this done.

I think we need to come up with a better means of communication outside of the forum and a place where we can track who is working on what and when. the only thing i feel we have a deadline with is the server move. The rest will get finished when it gets finished. so no deadlines. people never do their best when pushed to hard or spread to thin. and if it is getting to be to much say so.

And simply put. our top priority is the users. if they need help or have a question. stop to help them out. I do not want the forum to go back to what it was where so many questions would go unanswered even if you do not have the answer doesn't matter still acknowledge them and spend the time to learn it. or find someone that may have the answer. Because if we do not do that then what are we really going through all of this for? No users = No reason to continue making EG better. I know i personally am doing this for myself. because it brings me happiness making other people happy. It makes my life better. and the side affect of that is making others better as well. and I know that each and every single one of you get an awesome feeling when someone says they are new to EG and that it is a kick ass program. and that they don't know what they would have done if EG didn't exist. There is no monetary gain from doing this. there is something much better..... sense of pride, accomplishment, personal success at making something work, there are a million of them. but you only get those feelings when the user compliments you on it. and the user can't do these things unless you interact with them. so forum presence is and always should be at the very top of the must do list.

If at any point you are getting burnt out on EG.. then guess what that means. you have not spent enough time interacting with the users. tell us this and go into the forums and help people out. this is why i keep on working with the plugins. because just one person getting excited and giving you compliments gives me motivation and lifts me back up. and reminds me of why I am doing this.

sorry for going off on a tangent there but those are my thoughts. and if any of you have any suggestions as how to collaborate in a more efficient manner then by all means lets do it.

and I also want to personally show my gratitude to everyone that has helped and is helping we all notice and see the help and the things you are doing. and we don't all voice it THANK YOU so much for all of the efforts and hard work. and some day mark my words some day I will be in a position to show that gratitude. EG is one of if not the longest running HA project in existence and I would like it to remain that way. and I an sure everyone wants it the same way as me. and with all the effort that is being put in today and tomorrow and the day after is going to make it that way.

Posted: **Sun Jun 11, 2017 11:20 pm**

topix wrote: 1, 2 and 4 are maintained from (github) repository and 2 is maintained from forum users.

Did i get it right?

I think that's the proposal except the last number in the above statement should be 3 instead of 2, but I'm sure we all knew what you meant.

dequi wrote:Wow... that is really still all over the place

I somewhat agree but I don't think that is a huge problem because the source of the content for each is logical. The source of eventghost.net/wiki is the users publishing directly to that wiki, which makes sense. The source of the help file and user documentation is the documentation files contained in the EventGhost repository at _build/data/docs, which makes sense. If I understand correctly, the developer documentation is automatically generated from the docstrings in the EventGhost code.

The systems for the first two are already in place and working well so it really comes down to the developer documentation publishing system. Would there be a benefit to using the same system for publishing the user documentation and the developer documentation? If so, the logical first option to consider is to adapt the current documentation publishing system to be used for the developer documentation, which would mean publishing the developer documentation under eventghost.net/documentation. The alternative is to create a new system for publishing the developer documentation and then also use that system for publishing the user documentation.

dequi wrote: kgschlosser stated somewhere that there is a build methodology to go from build to mediawiki implemented but not used.
well why not consolidate it all in an uniform way using namespaces

I think it's a reasonable proposal but it really hinges on the system of automatically generating MediaWiki markup and publishing to the wiki. If this proposal is to be pursued further I think we would need to know more about the existing system to determine whether it's ready to go, needs work, or must be created from scratch. It seems like the process of publishing the developer documentation to the GitHub wiki would be pretty straightforward because you can just use git push, the problem of generating GitHub Flavored Markdown from the docstrings remains but there is more likely to be an existing solution for this since Markdown is more common than whatever markup MediaWiki uses.

kgschlosser wrote: so anyone that wanted to spearhead translating or adding information in another language would be able to do this. now i do know that this is kind of an odd duck from a management stand point. because any of the core coders will need to have global write access to the docs. user/code/help but we need to keep things correct and there should be only one "head" of the user/code/help

I don't understand how this would work. Couldn't it all be handled via pull requests, or are you talking about changes that need to be made to the website backend?

kgschlosser wrote: pearbear does have a good knowledge of programming and an excellent knowledge of documentation I would still like to see him take on this challenge.

I'd need to have more details on this. It might be beyond my abilities/free time. I'm certainly interested in working on documentation. I don't claim to have special skills in writing/editing documentation other than that I'm actually willing to do it (which many programmers are not) and I'm a native English speaker, which makes it a bit easier for me than for someone who speaks English as a second language.

kgschlosser wrote: I know that @topik2k has been overwhelmed with real life work. and I do know this happens to all of us. and we do not want to intrude on that. everyone has a life beyond EG and has families to take care of and moneys to be made. So if you need to slow down with work on EG then simply let us know. this way we don't want to bother ya. Family and providing for them is always first and foremost and I think that we can all agree on that. life will go on in EG land and you will not be left behind. What would also help is if you possibly left one person in charge of communication with ya. this way you know that if that person asks something it is going to be something important so you won't get beat up with menial things.

I agree, we're all volunteers and I'm very grateful for whatever time anyone is able to contribute. I do feel that there should be an obligation for people to make it clear their level of commitment to the project and take the time to communicate when that changes. For my part:

I was made one of the admins of the wiki usergroup. I commit to handling any requests to join that group within 24 hours. If I am taking longer than that people are welcome to send me a PM.
I am committed to monitoring all changes to the MediaWiki and reverting any spam or vandalism and removing the user from the wiki usergroup if necessary. If I overlook anything people are welcome to send me a PM.
I am committed to migrating the tutorials from the forum to the wiki. I've just been waiting for the dust to settle a bit to make sure we're all on the same page with the wiki.

kgschlosser wrote: I think we need to come up with a better means of communication outside of the forum

I prefer to keep discussion public whenever possible. I think the forum and GitHub comment threads should be sufficient. There is also a "Talk" page for every MediaWiki page. The exception would be any security sensitive information.

kgschlosser wrote: If at any point you are getting burnt out on EG.. then guess what that means. you have not spent enough time interacting with the users.

It goes both ways for me. I can get seriously burned out dealing with people on the Arduino forum and Stack Exchange every day. Then I need to back off and commit some code or report some bugs. The EventGhost forum has a higher quality of threads than the Arduino forum so it's not such a problem here. But I agree that it's a wonderful feeling when you can help someone get past a problem they've been struggling with. It's also very important to be able to see things from the user's viewpoint, especially new users. If you never interact with them then you lose sight of that.

Posted: **Mon Jun 12, 2017 3:05 am**

pearbear wrote: kgschlosser wrote:
so anyone that wanted to spearhead translating or adding information in another language would be able to do this. now i do know that this is kind of an odd duck from a management stand point. because any of the core coders will need to have global write access to the docs. user/code/help but we need to keep things correct and there should be only one "head" of the user/code/help

I don't understand how this would work. Couldn't it all be handled via pull requests, or are you talking about changes that need to be made to the website backend?

Anything that is done with translations has to be done manually not programmatically. These translations would have to be added to the different documentation areas by whomever has the ability to do it.

when i say docs i mean all documentation

There should be only one person that makes sure the formatting/spelling is correct. things of that nature. I would like to be able to go and browse the media wiki and then go to the code wiki and everything is laid out in the same way (or as close as possible). This will make it easier to manage due to one style of formatting.

the reason i state the global write access. i should have stated on the back end. This would be if there are any mechanism that would need to be modified for any kind of an automatic doc creation/update from the builder.

This is what i see as far as options and what is supposed to be written to where and this is simply for an understanding not specifically about what content goes into which one as that can be sorted out as we encounter gray area topics.

option 1:
Everything can go into a single media wiki instance (bad idea i think)

option 2:
code help/user help gets packaged with EG (how it is now) (personally i do not see a need to add coding information to the help as this is above what a normal user would do)
media wiki is for tutorials/plugin docs pretty much everything that you wouldn't want to put into the packaged help files

option 3:
media wiki is for the tutorials/plugins
github wiki is for code
help docs is for the basic usage of EG

option 4:
media wiki is for code/tutorials/plugins (don't like the idea of mixing the 2)
help is help

option 5:
media wiki is for tutorials/plugins
a second media wiki instance for the code
help is help

option 5:(this would be 3 databases in mysql and 3 running instances of media wiki of which the help and the code would be version/language)
media wiki 1 tutorials/plugins
media wiki 2 code
media wiki 3 online help docs

option 6:(this would be 2 databases in mysql and 2 running instances of media wiki)
media wiki 1 tutorials/plugins
media wiki 2 online help docs
github wiki code

Now i personally like the last 2 don't know which one i am in favor of more. but for ease of maintenance for us i would think number 5 would be the best but number 6 would have the benefit of the github wiki being more geared around code. so whatever you guys decide would be the easiest to manage as well as the easiest for the user to understand\navigate. Now remember the management part. I went through that spiel earlier for a purpose. everyone has Family so which ever you feel would lessen a possible burn out would be my suggestion

Posted: **Mon Jun 12, 2017 4:09 am**

kgschlosser wrote: These translations would have to be added to the different documentation areas by whomever has the ability to do it.

when i say docs i mean all documentation

Here's how I see it working:

User documentation:
Create a folder structure in the EventGhost repository:

Code: Select all

_build
|_data
   |_docs
      |_de
      |_en
      |_es

and so on, adding a new language folder as each translation is done. So all someone needs to do to translate the user documentation is to submit a pull request to the EventGhost repository.

Developer documentation:
If I understand correctly, this will be generated from the docstrings in the EventGhost code, so the only way to handle translations is to add them to the docstrings, also via a pull request to the EventGhost repository.

Wiki content:
If someone wants to translate a wiki page they should add a link to the top of that page that points to their translated page.

kgschlosser wrote: There should be only one person that makes sure the formatting/spelling is correct.

That person would need to be multilingual. I think we just need to be grateful if someone provides a translation and then count on the community to report or fix any typos in those translations.

With the level of community participation we currently see in this project I'm just not sure if documentation translation would be beneficial. The problem is that documentation is continually evolving, that means translation is an ongoing task. If I contribute a change to the English documentation then either someone fluent in each of the translated languages needs to make the equivalent change or else those translations become outdated. I'm not convinced that we have people committed to doing this work. So it becomes a question of whether non-English speakers would prefer up to date documentation in English or outdated/incomplete documentation in their native language. It is very common for people to have a decent familiarity with the English language and they also have Google Translate, etc. to fall back on. So I think we need know if anyone here is willing to do the initial translation work, whether they are willing to do ongoing updates, and which language. Then we can determine if it's worth the work to set up the infrastructure necessary to publish the user and developer documentation in multiple languages.

As for the wiki content, I think that's fine if people want to add translated versions of the wiki pages. It won't require any work to set it up so go for it!

kgschlosser wrote: I would like to be able to go and browse the media wiki and then go to the code wiki and everything is laid out in the same way (or as close as possible). This will make it easier to manage due to one style of formatting.

Sounds like a good idea. We just need a documentation style guide.

Posted: **Mon Jun 12, 2017 11:57 am**

@pearbear I do know that the person that is checking spelling and things of that nature is not going to be able to do all of the languages, and with the multi lingual stuff for the code wiki it cannot be added to the doc strings unfortunately this would have to be something that is able to be done after the build process. But I am speaking for all the documentation as well. but mostly the core help files. not saying that the translations are going to happen soon or even that they will happen. but if someone comes along that can do it for us then great and we should be set up to be able to handle it.

I do not know if this would be an easier way to go about it then to specifically create a new wiki code/plugin/help per version. would it be easier to add a flag or some kind of a marker to the entry for which version(s) that it works with? would that be easier to maintain?

EventGhost

Media Wiki

Re: Media Wiki

Re: Media Wiki

Re: Media Wiki

Re: Media Wiki

Re: Media Wiki

Re: Media Wiki

Re: Media Wiki

Re: Media Wiki

Re: Media Wiki

Re: Media Wiki

Re: Media Wiki

Re: Media Wiki

Re: Media Wiki

Re: Media Wiki

Re: Media Wiki