Sorry your browser is not supported!

Hi,

We know the AppGameKit help can at times be brief and to the point. We would love for the help to be far better and more informative. The problem we have is that we are a small team and we prefer to put all our efforts into coding the software (it's what we're best at).

We were wondering if some community members would like to volunteer and improve the help files.

Do you know of a great online way for us to collaborate together in this cause?

Let us know your thoughts and if you can help us improve our AppGameKit baby.

Rick & the AppGameKit dev team

Hi!

I would like to help... but my english is not very good (i need review).

Perhaps, it would be a good idea if you will create a new board inside APP Game Kit forum with the title: "AGK help".

We can create new topics with each command and upload new files for replacing the old help... When you release a new version, a forum user send you the new help by email (for example).

Would it be a good idea?

edit: By email, it's not logical (30 MB), but you can use Box.net.

AGK wiki would be good.

http://appgamekit.wikispaces.com/

Simply replace it with the "Hands on AppGameKit basic" Book, I regard that as THE help file, for AGK. You would have to pay the author for each sold copy of AppGameKit though.

Thing is, it's design is worse than http://www.appgamekit.com/documentation/

TGC could install their own wiki though (on http://www.appgamekit.com/documentation/ or maybe http://www.documentation.appgamekit.com/), or code their own editing system ( I wonder if they have time, through )

In any case, here's a list of wiki software:

http://en.wikipedia.org/wiki/List_of_wiki_software

I'd simply "hire" (for free, from forums ) few moderators for it, and put up that if somebody tries to make changes, they have to be accepted by one of admins/mods.

(PS. DokuWiki would fit in perfectly, I think)

Simple as that I guess.
Or just use http://appgamekit.wikispaces.com, although, that's not official and people might put all sort of stuff there. (Bad stuff aswell)

It is a known fact that not everyone is happy with the documentation. And with good reason. The current, official, AppGameKit documentation is written for the beginners and often lacks details needed by the more advanced programmers.

However, it is fairly safe to assume that there would be some enthusiasm and volunteer support from the community to improve the documentation!

But since there is no official AppGameKit Documentation Wiki, I believe many community members are reluctant to submit considerable writing effort to a community based wiki; which may or may not be there tomorrow.

Also, the problem with those is dispersion of information and duplication of effort. (The AppGameKit Community Wiki by erebusman started by duplicating all information from the AppGameKit documentation. It was then assumed that the duplicate would be modified and improved upon, but the number of page edits on the community wiki has still remained very low.)

There should only be ONE official Documentation Wiki that we can rely on! (Unfortunately the reliability of community created Wikis is always suspect.)



If only there was one perfect solution, I would recommend it immediately.

However, there are many many many solutions! And those will need to be carefully evaluated. (Which is a fairly considerable task in itself.)

The reference to the wiki-list given by Kamac is a good starting point, of course.

Personally, I've always been a big fan of MediaWiki, but I did take a look at DocuWiki, and it might be a good solution. (This volunteer documentation effort will not happen if it isn't kept simple.)



So, here are some additional thoughts... These thoughts may break the "keep it simple studid" guideline.

DECIDE AN OVERALL DOCUMENTATION FORMAT

Writing good documentation is not easy - but there are plenty of online documentation resources with very well thought out content structures; which is very important.

Check out the PHP Manual for a GREAT example:
http://php.net/manual/en/index.php

Also, if you've ever done any serious programming using Microsoft technologies, then the MSDN Library will be familiar to you. MSDN contains developer documentation for pretty much everything Microsoft has ever released:
http://msdn.microsoft.com/en-us/library/

The function references have a standardized format, designed by professionals for professionals, with a footer section for "community additions".

Although personally I think the PHP Manual really is even better and easier to read. (The excessive brightness of the new MSDN format has always bothered me, custom CSS fixes that though.)

EVALUATE AVAILABLE TECHNOLOGY SOLUTIONS

Here are a few links to get started with testing EtherPad:
http://en.wikipedia.org/wiki/Etherpad
http://etherpad.org/
https://github.com/ether/etherpad-lite/wiki/FAQ

(However, Etherpad alone is not a good solution.)

Here are the links about combining DocuWiki with Etherpad:
http://starburst.hackerfriendly.com/?p=1808
http://starburst.hackerfriendly.com/?p=1836
https://canidu.com/etherwiki-howto.html

MODERATION

All (well, let's say most) wiki's have version control, which makes it very simple to eliminate unwanted content by reverting changes. (I think Kamac was simply overlooking this fact in his post.)

Therefore, I would say that tight moderation is not required. It will promote neither the creation of new content, nor updates to current documentation.

It should be enough if only registered users are allowed to modify content. When those user's do not behave, they can be either temporarily or permanently banned from the Wiki.

IT'S YOUR PRODUCT(S), SO YOU HOST THE DOCS

TGC will have to create an "official" AppGameKit Documentation Wiki, or just AppGameKit Wiki for short.

I think this may be even more important than deciding on the exact technology used to create the community authored documentation.

And while you're thinking about volunteer support for writing AppGameKit documentation, how about extending the same concept to other TGC products aswell. Therefore, a primary TGC Wiki portal might not be a bad idea at all.

Cheers,
AgentSam - The grumpy old software engineer

@RickV,

After speaking to Paul a little and trying to work through the IAP for Android, I created a help doc of sorts for that process including some non AppGameKit related pitfalls to avoid, but was waiting for the next update. Will happily forward what I wrote for you if you want though.

As a general comment, I would disagree with AgentSam when he said the documentation is written for beginners without the detail needed for more advanced coders...I would say that the documentation is occasionally quite lacking for both. Take as an example the code to download an http file, it reads simply as
however what isn't clear (I don't think) is that the file paths need to be included, or that is the name to save the file as and not the local name of the file on the server that you want to download. To me, that suggests such and the assumption is that the downloaded file will automatically have the same name, and be in the media folder.

I still use DBPro these days (and still love it!), and the help files in that are ten times more helpful for one reason alone: examples of the commands being used in the help file. Generally, that clears most things up right away, in one place. I know there's an examples section, but this seems quite forgotten about for some commands.

Just my thoughts.

P.s. it might also be nice to have some form of "concepts" section expanded. For example, I recently saw someone post on the DBPro forums that they wanted the ability to have a background streaming service running through DBPro with a single command. Obviously, that's probably not possible, but the concept itself IS possible using some clever workarounds, and that would be nice to see expanded upon with AppGameKit in the help, for more advanced users (or perhaps less experienced users is the better phrase).