Sorry your browser is not supported!

You are using an outdated browser that does not support modern web technologies, in order to use this site please update to a new browser.

Browsers supported include Chrome, FireFox, Safari, Opera, Internet Explorer 10+ or Microsoft Edge.

AppGameKit Classic Chat / Help files/Manual

Author
Message
IanM
Retired Moderator
21
Years of Service
User Offline
Joined: 11th Sep 2002
Location: In my moon base
Posted: 18th Jan 2011 19:31
Going to get myself a stern-looking-at from Lee/Rick/Mike/Paul here I suspect (not Ravey, as you have to be able to stop grinning to do that and I don't believe he's capable of that), but please can we have some more accurate and helpful help files this time around?

In that vein, and to hopefully help with that, is it possible for you guys to put the help files on-line into a privately writeable/publicly readable wiki as you do them so we can see what's happening?

(NOTE: This isn't to measure your progress, as you can generate help files before the command exists - I find that sometimes designing the command-set up front and writing the docs for it, helps to steer the code and the command-set in the right direction).

Michael P
18
Years of Service
User Offline
Joined: 6th Mar 2006
Location: London (UK)
Posted: 18th Jan 2011 20:38
It is worth using something like doxygen, makes maintaining documentation much easier.

baxslash
Valued Member
Bronze Codemaster
17
Years of Service
User Offline
Joined: 26th Dec 2006
Location: Duffield
Posted: 18th Jan 2011 23:53
I really agree here.

The DBP help files often have examples that are no 'help' whatsoever...

Libervurto
17
Years of Service
User Offline
Joined: 30th Jun 2006
Location: On Toast
Posted: 19th Jan 2011 01:09
TGC could even hold a competition for users to write tutorials for AGK.


Everything worthwhile requires effort.
defiler
14
Years of Service
User Offline
Joined: 4th Apr 2009
Location: Canada
Posted: 19th Jan 2011 02:21
Better yet, a community tutorials guide!

Current Project: Lost Contact: Station 7
ShaunRW
DBPro Developer
16
Years of Service
User Offline
Joined: 7th Jan 2008
Location: Brisbane, Australia
Posted: 19th Jan 2011 05:12
Wiki like help files that users can edit to be more helpful would be awesome.

baxslash
Valued Member
Bronze Codemaster
17
Years of Service
User Offline
Joined: 26th Dec 2006
Location: Duffield
Posted: 19th Jan 2011 10:00
Quote: "Wiki like help files that users can edit to be more helpful would be awesome."

That's a really great idea! I would love to be able to add to or edit a wikipedia style Help site

It would need careful moderation to stop spammers and... well idiots.

RickV
TGC Development Director
23
Years of Service
User Offline
Joined: 27th Apr 2000
Location: United Kingdom
Posted: 19th Jan 2011 10:28
Hi,

Yes we are mindful to ensure we do this the best possible way. We will talk internally as to the best way to do it and get back to you.

Rick

Financial Director
TGC Team
Fatal Berserker
13
Years of Service
User Offline
Joined: 2nd Jul 2010
Location:
Posted: 19th Jan 2011 13:31
A wiki system would be good.

LeeBamber
TGC Lead Developer
24
Years of Service
User Offline
Joined: 21st Jan 2000
Location: England
Posted: 20th Jan 2011 04:10
Hi Guys,

I totally agree about documentation. In fact, one of the first coding conventions for the development team was the implementation of a documentation system that is part of the actual function source code so as we add commands/functions/etc the documentation is automatically generated It's also the best place to keep the source of the documentation (right next to the code it relates to) so we can go nuts adding lots of juicy details which are then exposed as the final documentation. I also would like to see a direct conduit between this automated generation and a public server where said documentation can be viewed as soon as an update is checked in. I could do it now with Google Code and SVN, but maybe there is a more Wiki style solution out there (i.e generate a Wiki page from our auto-generated HTML help pages and then automatically broadcast them to the server

I drink tea, and in my spare time I write software.
BillR
21
Years of Service
User Offline
Joined: 19th Mar 2003
Location: United States
Posted: 20th Jan 2011 06:30 Edited at: 20th Jan 2011 06:32
The BEST feature of the DBPro help system is its integration in the editor! Pressing F1 is wonderful.
Whatever you do, DON"T have the primary help system web based.
If you want a secondary system on the web then fine, but I spend lots of time on the road with slow internet access.
I use the F1 help system all the time in DBPro since it is local and fast.
Green Gandalf
VIP Member
19
Years of Service
User Offline
Joined: 3rd Jan 2005
Playing: Malevolence:Sword of Ahkranox, Skyrim, Civ6.
Posted: 20th Jan 2011 18:06
Quote: "The BEST feature of the DBPro help system is its integration in the editor! Pressing F1 is wonderful."


Definitely.

I groan whenever I need to get Help on basic Windows functionality and have to wait ages for a page to download.

About 30 years ago there was a PC revolution which meant everything was put on local machines. Suddenly there seems to be a counter-revolution in full swing. Who's driving it and why?
Phaelax
DBPro Master
20
Years of Service
User Offline
Joined: 16th Apr 2003
Location: Metropia
Posted: 20th Jan 2011 18:37
You don't even get manuals with apps/games anymore. Typically, you'll get a single pdf on a cd which simply contains a link to a website to view the manual.

"Only the educated are free" ~Epictetus
"Imagination is more important than knowledge..." ~Einstein
Green Gandalf
VIP Member
19
Years of Service
User Offline
Joined: 3rd Jan 2005
Playing: Malevolence:Sword of Ahkranox, Skyrim, Civ6.
Posted: 21st Jan 2011 01:18
Exactly what I'm complaining about.
The Slayer
Forum Vice President
14
Years of Service
User Offline
Joined: 9th Nov 2009
Playing: (Hide and) Seek and Destroy on my guitar!
Posted: 21st Jan 2011 01:36
Yeah, I also highly suggest to have the help system integrated in the IDE. People don't allways have a (good) online connection available, and pressing the F1 key works faster aswell.
A Wiki page is really good too, so I think both should be available.

Cheers

SLAYER RULES! YEAH, MAN!!
DMXtra
21
Years of Service
User Offline
Joined: 28th Aug 2002
Location: United States
Posted: 21st Jan 2011 10:25 Edited at: 21st Jan 2011 10:26
Maybe what can happen is that the IDE checks the server once in a while and downloads new changes to the help files.

This way as new changes are made on the server, the IDE can check every once in a while or you can manually check as well (in case you are not online). Then it pulls down help file updates.

A setting is in place so that help files are updated and you are notified (think Windows updates, but for help files). I can either download them manually by pushing a button or it can check once in a while.

This way you always have updated help files and they are always being updated so you don't miss out on anything and you instantly get the help by pressing [F1].

This way everyone wins

Dark Basic Pro - The Bedroom Coder's Language of choice for the 21st Century.
Green Gandalf
VIP Member
19
Years of Service
User Offline
Joined: 3rd Jan 2005
Playing: Malevolence:Sword of Ahkranox, Skyrim, Civ6.
Posted: 21st Jan 2011 13:11
Yes.
IanM
Retired Moderator
21
Years of Service
User Offline
Joined: 11th Sep 2002
Location: In my moon base
Posted: 21st Jan 2011 13:43
No.

That's OK as long as the help matches the compiler/command versions, and as long as when third-party commands are introduced, the same updates can happen from there. Otherwise, I'd say that the help should be updated with the compiler or plug-in installation.

Scraggle
Moderator
20
Years of Service
User Offline
Joined: 10th Jul 2003
Location: Yorkshire
Posted: 21st Jan 2011 13:47 Edited at: 21st Jan 2011 13:48
Quote: "IDE checks the server once in a while and downloads new changes to the help files"


No.

I have my help files personalised to include 3rd Party commands in the main contents page and have adjusted all the 3rd part commands to match the style of the main commands.
It is annoying enough now that I have to remember to back-up my help files when updating DBP and then replace my changes each time. It would be impossible if the help files were updated automatically.

dark coder
21
Years of Service
User Offline
Joined: 6th Oct 2002
Location: Japan
Posted: 21st Jan 2011 14:18
There really should be a publicly editable wiki from day one, if the last 10+ years are any indication, there won't be decent documentation that gets frequently updated with language changes(I said it!). It could also be used to list various algorithms and coding patterns that aren't exactly easily found in the code snippets board.

Green Gandalf
VIP Member
19
Years of Service
User Offline
Joined: 3rd Jan 2005
Playing: Malevolence:Sword of Ahkranox, Skyrim, Civ6.
Posted: 21st Jan 2011 16:43
Quote: "That's OK as long as the help matches the compiler/command versions, and as long as when third-party commands are introduced, the same updates can happen from there. Otherwise, I'd say that the help should be updated with the compiler or plug-in installation."


Good point. Please interpret my previous "Yes" as "No".

As for having to have Internet access to read the Help files, definitely NO (case sensitive and bold ).
DMXtra
21
Years of Service
User Offline
Joined: 28th Aug 2002
Location: United States
Posted: 22nd Jan 2011 08:02
Quote: "
That's OK as long as the help matches the compiler/command versions, and as long as when third-party commands are introduced, the same updates can happen from there. Otherwise, I'd say that the help should be updated with the compiler or plug-in installation."


yeah, even better.

I like this a lot, it keeps the help updated and it keeps it offline, the only thing missing would be others adding to it so they can add even more content for the help files.

Dark Basic Pro - The Bedroom Coder's Language of choice for the 21st Century.
Diggsey
17
Years of Service
User Offline
Joined: 24th Apr 2006
Location: On this web page.
Posted: 22nd Jan 2011 11:19
Essentially, the latest version of the help files should be kept in some kind of wiki. The pages should be privately editable, but anyone should be able to use the talk pages.

At each update, a new copy of the help files are generated from the wiki by TGC, and then included with the update, so that you get to keep a local copy matching your current version.

[b]
Green Gandalf
VIP Member
19
Years of Service
User Offline
Joined: 3rd Jan 2005
Playing: Malevolence:Sword of Ahkranox, Skyrim, Civ6.
Posted: 22nd Jan 2011 11:56
Quote: "a new copy of the help files are generated from the wiki by TGC"


Not sure whether you are suggesting that us mere users can mess with the wiki version. Would TGC have to remove all the errors introduced by user edits?
Diggsey
17
Years of Service
User Offline
Joined: 24th Apr 2006
Location: On this web page.
Posted: 22nd Jan 2011 12:04
Quote: "The pages should be privately editable, but anyone should be able to use the talk pages."


[b]
bitJericho
21
Years of Service
User Offline
Joined: 9th Oct 2002
Location: United States
Posted: 22nd Jan 2011 12:34 Edited at: 22nd Jan 2011 12:35
Quote: "Not sure whether you are suggesting that us mere users can mess with the wiki version. Would TGC have to remove all the errors introduced by user edits?"


The Wiki should be public. With good mods, (which we already have), and a good wiki software, it would be trivial to inspect user changes on the wiki and would be infinitely more helpful than having stock, unchangeable documentation. (Just look at DBP docs, they get the job done, sure, but not the greatest)

Want to have less risk of abuse, require registration and require notes on edits. If there's not sufficient notes to even see what the change was, mods can auto-revert. I don't think it would really be a big problem though.

I'd like to see the editor automatically go online or stay offline as a user selected option.

For updates, it would be super easy to generate an offline file from the current state of the wiki.

[center]
Join the TGC Group!
http://tehcodez.groups.live.com
Diggsey
17
Years of Service
User Offline
Joined: 24th Apr 2006
Location: On this web page.
Posted: 22nd Jan 2011 12:44
I think the community should be able to add examples and things, but I don't like the idea of anyone being able to edit the help files. Ideally you would have the core text of the help files alongside the code in the SVN, so only people who can edit the code can edit this text.

The online version of the help files would automatically be updated to the text in the code, and so would not be editable, but there would be talk pages where anyone can make suggestions. The best suggestions would then get merged back into the original code.

Each help file should have a link to the online talk page.

The offline version of the help files should be a copy of the state of the wiki at the time of release, except for the talk pages. (But there would still be links to the online talk pages)

[b]
bitJericho
21
Years of Service
User Offline
Joined: 9th Oct 2002
Location: United States
Posted: 22nd Jan 2011 12:50 Edited at: 22nd Jan 2011 12:54
You know what, the PHP help documents I think are the best of both worlds.

The main documentation is not editable, but we can comment on it, offer examples, offer really cool snippets.

I'd like to see this. The help system in the IDE can download these comments if the user wants it to, so we can get the comments right alongside the documentation.

And every so often the comments can be pruned and placed on some other page so as not to keep people from posting, but can keep it from cluttering things up in the main documentation. (maybe each time a major document revision is released)

But it's important to have the comments easily accessible to the developer, nobody wants to click a billion links just to find the info they were looking for. I use cntl-f to find things, I hate when stuff gets cut up by links.

[center]
Join the TGC Group!
http://tehcodez.groups.live.com
Green Gandalf
VIP Member
19
Years of Service
User Offline
Joined: 3rd Jan 2005
Playing: Malevolence:Sword of Ahkranox, Skyrim, Civ6.
Posted: 22nd Jan 2011 13:15
@Diggsey

In other words you are not suggesting "a new copy of the help files are generated from the wiki" but more correctly "a new copy of the help files are generated for the wiki". Is that what you meant?

I'm happy with your subsequent clarifications.
Diggsey
17
Years of Service
User Offline
Joined: 24th Apr 2006
Location: On this web page.
Posted: 22nd Jan 2011 13:34
Basically, the both the wiki and the help files are generated from the code. (I think TGC already said they would put the help text in the code) and the pages on the wiki are private. Only the talk pages can be edited, so it doesn't matter if the help files come from the original code, or the wiki, as the wiki is an exact copy of the help text in the code.

The talk page is where anyone can post and suggest ideas/changes to the help text. If TGC decide to include these changes, they would make the changes to the help text in the code, and then the wiki would automatically update to show these changes.

Whenever an update is released the current state of the help text is included with the update, ensuring that the user always has the relevent version.

[b]
bitJericho
21
Years of Service
User Offline
Joined: 9th Oct 2002
Location: United States
Posted: 22nd Jan 2011 14:43
what im saying is that putting comments on the talk page sucks. Also, wiki talk pages suck.

It should be a comments box below the documentation on the same page, with bbcode support

[center]
Join the TGC Group!
http://tehcodez.groups.live.com
Green Gandalf
VIP Member
19
Years of Service
User Offline
Joined: 3rd Jan 2005
Playing: Malevolence:Sword of Ahkranox, Skyrim, Civ6.
Posted: 22nd Jan 2011 14:47
Quote: "Basically, the both the wiki and the help files are generated from the code. (I think TGC already said they would put the help text in the code) and the pages on the wiki are private. Only the talk pages can be edited, so it doesn't matter if the help files come from the original code, or the wiki, as the wiki is an exact copy of the help text in the code.

The talk page is where anyone can post and suggest ideas/changes to the help text. If TGC decide to include these changes, they would make the changes to the help text in the code, and then the wiki would automatically update to show these changes.

Whenever an update is released the current state of the help text is included with the update, ensuring that the user always has the relevent version."


Sounds good.
Jeff Miller
19
Years of Service
User Offline
Joined: 22nd Mar 2005
Location: New Jersey, USA
Posted: 27th Jan 2011 21:48
We had something akin to a wiki help file for DBPro to which members were contributing, maintained by Jess T. I for one found it useful. He could not get permission to have it on the TGC site. It died on the vine after a while. John Y was either going to resurrect it or incorporate it into a new help file, supposedly with the support of TGC, and I sent him a copy of Jess's database. That plan was suddenly scrapped. If this is going to work, give a trusted MOD the go-ahead, server space, and support.
Mike Johnson
TGC Developer
21
Years of Service
User Offline
Joined: 13th Sep 2002
Location: United Kingdom
Posted: 1st Feb 2011 10:06
Lots of useful feedback for us regarding the documentation. It's definitely an area for improvement! I expect the end result to be a mixture of options whereby you have all the documentation within the IDE (with optional updates) along with an online portal.
Jammy
21
Years of Service
User Offline
Joined: 15th Jan 2003
Location: Scotland
Posted: 6th Feb 2011 21:56
I feel the manual should be in a format that can easily be printed out on A4 Paper ready to be put in a ring binder. It should be in such a format that documentation on updates to AppGameKit (which i expect will be many) could be printed out and slotted in to the manual.

The manual should contain explanations for all commands in categorised chapters along with related commands and a simple example of usage.

Nights Bane
14
Years of Service
User Offline
Joined: 15th Dec 2009
Location:
Posted: 12th Feb 2011 01:25
I believe if you are online, and hold Ctrl + left mouse whilst within the eclipse editor whilst hovering above a command, it displays information about that command. I remember this from my experiments a while ago within directx programming... and personally, I would find a wiki AND the in built help great! why not have both!
Alquerian
17
Years of Service
User Offline
Joined: 29th Mar 2006
Location: Reno Nevada
Posted: 17th Feb 2011 01:37
I am on board for it!

Quote: "In fact, one of the first coding conventions for the development team was the implementation of a documentation system that is part of the actual function source code so as we add commands/functions/etc the documentation is automatically generated "


Nice idea, kind of like JavaDoc, it would be nice if the ADKDoc was automatically generated and versioned (1.1, 1.2) and navigating the versions would be a bit easier that way.

I would maintain the ADKDoc separate from a Wiki, where the Wiki references the ADKDoc. That way the Wiki could demonstrate examples and reference different ADKDoc versions.
LeeBamber
TGC Lead Developer
24
Years of Service
User Offline
Joined: 21st Jan 2000
Location: England
Posted: 15th Mar 2011 03:34
Currently we are generating the documentation directly from the source, and this is typically done after we add or change commands (for our own reference). It sounds like the solution, minus correct terms, is to generate PART A which is this core documentation dumped from the latest build of AGK. PART A is then uploaded as a Wiki update, which joins onto an existing PART B. PART B is all the comments, code, advice, tips that relate to each command in the Wiki (not sure how this can be done per command page, advice welcome).

For each update release, we snapshot the on-line Wiki (PART A + B) which becomes our off-line help system which is part of the latest update installer (instant local help). The same snapshot is uploaded back along with the updated installer to our on-line portal so the new commands/changes are instantly available on the day of release thus retaining contributions of comments, code, advice and tips provided to date (the PART B stuff). Just like forum moderators, we would appoint trusted valued members of the community to oversee what goes into the PART B stuff to ensure it remains clean and relevant.

Does this sound like the right solution all round? Vote YES if you think I am talking sense, and NO if you think I am talking pile

I drink tea, and in my spare time I write software.
DMXtra
21
Years of Service
User Offline
Joined: 28th Aug 2002
Location: United States
Posted: 15th Mar 2011 06:33
I vote YES, this sounds like the best solution overall. Just archive everything in a small package so that it can be downloaded quickly and you are good.

Dark Basic Pro - The Bedroom Coder's Language of choice for the 21st Century.
IanM
Retired Moderator
21
Years of Service
User Offline
Joined: 11th Sep 2002
Location: In my moon base
Posted: 15th Mar 2011 15:14
YES.

I'm for any help system that is easily maintainable and enforces maintenance.

For example, I'd suggest that whenever any new command is added that the final-build mechanisms you use will flag an error if the help has not also been added.

Digital Awakening
AGK Developer
21
Years of Service
User Offline
Joined: 27th Aug 2002
Location: Sweden
Posted: 15th Mar 2011 15:34
YES

And I also agree with IanM.

bitJericho
21
Years of Service
User Offline
Joined: 9th Oct 2002
Location: United States
Posted: 15th Mar 2011 22:37
Yes!

[center]
Join the TGC Group!
http://tehcodez.groups.live.com

Login to post a reply

Server time is: 2024-03-29 08:06:22
Your offset time is: 2024-03-29 08:06:22