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 / Which parts of the HELP need more detail?

Author
Message
JimHawkins
14
Years of Service
User Offline
Joined: 26th Jul 2009
Location: Hull - UK
Posted: 22nd Apr 2013 00:30
Link
I have to say I totally disagree. The help should be, IMHO, clear and straight-forward, from the developers. I do not want to wade through user Wikis.

-- Jim DO IT FASTER, EASIER AND BETTER WITH AppGameKit FOR PASCAL
Back to top
Profile PM Website
xCept
21
Years of Service
User Offline
Joined: 15th Dec 2002
Location:
Posted: 22nd Apr 2013 04:50
Link
Quote: " I have to say I totally disagree. The help should be, IMHO, clear and straight-forward, from the developers. I do not want to wade through user Wikis."


Agreed, as a baseline the documentation must be clear and extensive enough that the majority of users won't need to look elsewhere to understand a command. I believe the Processing documentation has been mentioned previously as a poster child for clear and concise documentation. Each command is documented with a bare bones code snippet and preview of the output, clear description, syntax definition and return data. As a result of this I was able to learn the gist of the language in a day and each command is very easy to understand. The site also has an official wiki the house advanced tutorials and information, but the reference material stands by itself.

I'm also not opposed to the PHP style documentation. The core documentation is provided (hopefully in a manner described previously) but there is a user feedback section at the bottom for others to contribute code snippets and additional examples. The offline documentation could simply have a link at the bottom pointing to the online version with user comments.
Back to top
Profile PM Email Website
Ched80
13
Years of Service
User Offline
Joined: 18th Sep 2010
Location: Peterborough, UK
Posted: 26th Apr 2013 16:42
Link
Just looked at the help for "SetFolder", I'm sorry but it's just horrible. It's just a huge mass of text and it makes it really difficult to understand how to use this command. In the end I gave up and just put everything in the root.

Back to top
Profile PM Email
Ancient Lady
Valued Member
20
Years of Service
User Offline
Joined: 17th Mar 2004
Location: Anchorage, Alaska, USA
Posted: 26th Apr 2013 17:59
Link
You must be looking at the v10811 version. It is terrible!

The v1076 version is a bit more readable.

Yes, that particular command help needs to really be made clearer.

The information is pretty good, but the layout is very bad.

It actually (in terms of raw content) is better in the newer version for explaining things and how to use the command.

Cheers,
Ancient Lady
AGK Community Tester and AppGameKit Master
Back to top
Profile PM
bitJericho
21
Years of Service
User Offline
Joined: 9th Oct 2002
Location: United States
Posted: 19th May 2013 20:44
Link
What about allowing comments on each command? Then on future releases those comments could be added into the documentation and the relevant comments could be cleared out

Visit my blog http://www.canales.me.
Back to top
Profile PM Email Website
The Zoq2
14
Years of Service
User Offline
Joined: 4th Nov 2009
Location: Linköping, Sweden
Posted: 19th May 2013 22:42
Link
That's a pretty good idea...

Also, when I read the documentation earlier today, I found that clicking on the link to each command takes a (short) while. And I usualy just use the documentation when I don't remember to parameters for a function, so adding the parameter to the links would make the documentation faster to use.
Back to top
Profile PM Email
bitJericho
21
Years of Service
User Offline
Joined: 9th Oct 2002
Location: United States
Posted: 22nd May 2013 06:04
Link
Breadcrumbs would be nice too.

Visit my blog http://www.canales.me.
Back to top
Profile PM Email Website
Phaelax
DBPro Master
21
Years of Service
User Offline
Joined: 16th Apr 2003
Location: Metropia
Posted: 22nd May 2013 13:15 Edited at: 22nd May 2013 15:32
Link
The lack of breadcrumbs annoyed me enough that I decided to create them myself.

http://www.zimnox.com/resources/agk/

I also noticed that every single HTM file included the same 400 lines of javascript and CSS.

After looking at the help for "SetFolder", it is a complete mess. There are multiple typos and reference to the wrong command. When it refers to SetRawWriteFolder, the command should actually be called SetRawWritePath. However, while that is the command that shows up in the IDE, the help page linked to it is called SetWritePath. Maybe the planned on changing it to match the GetWritePath command?

I took the liberty of trying to rewrite the page for that command, hopefully this sounds clearer and is easier to read:
http://www.zimnox.com/resources/agk/docs/?c=SetFolder

Quote: "I found that clicking on the link to each command takes a (short) while."

Must be your computer, because it opens instantly on mine.

"You're all wrong. You're all idiots." ~Fluffy Rabbit
Back to top
Profile PM Email Website
JimHawkins
14
Years of Service
User Offline
Joined: 26th Jul 2009
Location: Hull - UK
Posted: 22nd May 2013 13:44
Link
Very nice indeed.

The last statement should be modified. Windows can use / - it's just the DOS Shell that can't.

Personally, I liked the Amiga Autodocs system. These were generated out of comments in the C source, so that when a system call was modified or something added this was reflected in the docs. Programmers have too much to do to bother with updating separate documentation, and third-party help updaters are usually behind the leading edge - as we frequently see with AGK.

-- Jim DO IT FASTER, EASIER AND BETTER WITH AppGameKit FOR PASCAL
Back to top
Profile PM Website
Phaelax
DBPro Master
21
Years of Service
User Offline
Joined: 16th Apr 2003
Location: Metropia
Posted: 22nd May 2013 14:37
Link
Java docs are generated by code as well.

"You're all wrong. You're all idiots." ~Fluffy Rabbit
Back to top
Profile PM Email Website
JimHawkins
14
Years of Service
User Offline
Joined: 26th Jul 2009
Location: Hull - UK
Posted: 22nd May 2013 14:43
Link
Yip - I can generate Javadoc straight from Delphi. Helps me when I've forgotten what something I programmed years ago does!

-- Jim DO IT FASTER, EASIER AND BETTER WITH AppGameKit FOR PASCAL
Back to top
Profile PM Website
Paul Johnston
TGC Developer
21
Years of Service
User Offline
Joined: 16th Nov 2002
Location: United Kingdom
Posted: 22nd May 2013 18:36
Link
That is a good write up of the SetFolder command Phaelax, do you mind if I copy it into the official help documents?
Back to top
Profile PM Email
Phaelax
DBPro Master
21
Years of Service
User Offline
Joined: 16th Apr 2003
Location: Metropia
Posted: 22nd May 2013 21:48
Link
Go right ahead.

"You're all wrong. You're all idiots." ~Fluffy Rabbit
Back to top
Profile PM Email Website
AgentSam
12
Years of Service
User Offline
Joined: 14th Mar 2012
Location: Virtual Space
Posted: 24th May 2013 00:33 Edited at: 24th May 2013 00:50
Link
After I upgraded to AppGameKit 108.12 and did a comparison of some of the changes, I haven't been able to get the following thoughts out of my head.
So I'm dumping the thoughts here... So, to begin with:

JimHawkins wrote:
Quote: "I have to say I totally disagree. The help should be, IMHO, clear and straight-forward, from the developers. I do not want to wade through user Wikis."


Phaelax wrote:
Quote: "The lack of breadcrumbs annoyed me enough that I decided to create them myself.
http://www.zimnox.com/resources/agk/"


RickV wrote:
Quote: "You can read all the current help for V1.07 online here;
AGK V1.07 Online Help"


RickV wrote:
Quote: "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."


BatVink wrote:
Quote: "http://appgamekit.wikispaces.com/"


kamac wrote:
Quote: "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 )"


Does anyone notice what's wrong with this?

TGC is not really moving forward with the "AGK documentation project", although ideas have been thrown, guidance has been given, and usermade documentation copies have been created.

But the situation has not improved one tiny bit, because although there are some fixes in the latest AppGameKit 108.12 docs, these changes have not trickled down into the various wikis and documentation copies. The situation is calling out for centralization - a TGC hosted wiki! Seriously guys. This IS what we need (despite JimHawkins's opinion to the opposite.)

Always keep the latest version of the docs in a TGC hosted AppGameKit Help wiki...

I request all the myriad of outdated usermade wiki content be deleted, because ... Nobody likes to wade through [outdated] user Wikis. (In this respect Jim is absolutely correct.)

So, what is TGC going to do about this? Are we just going to wonder about the situation until the sun burns out or do something, at least get it started.

Cheers,
AgentSam
Back to top
Profile PM
JimHawkins
14
Years of Service
User Offline
Joined: 26th Jul 2009
Location: Hull - UK
Posted: 24th May 2013 01:25
Link
I remain utterly opposed to the Wiki approach because the definitions should be clear, scientific, and not requiring arbitrary comment. That's what I'm used to, and that's what I expect.

Comments are for forums.

-- Jim DO IT FASTER, EASIER AND BETTER WITH AppGameKit FOR PASCAL
Back to top
Profile PM Website
AgentSam
12
Years of Service
User Offline
Joined: 14th Mar 2012
Location: Virtual Space
Posted: 24th May 2013 01:32 Edited at: 24th May 2013 01:34
Link
Quote: "the definitions should be clear, scientific, and not requiring arbitrary comment. That's what I'm used to, and that's what I expect."


Jim,

That is exactly what I would expect also.

If a wiki would not provide this, it would not be the fault of the wiki, it would be the fault of the writers.

Do you not have faith that there are good documentation writers in the community?
(Ones that are possibly better than RickV and Paul?)

I dare say, there are. And like RickV has often said, their team is small, and can use all the help they can get.

What we need, is the wiki platform to support giving that help to them. No?

Cheers,
AgentSam
Back to top
Profile PM
Phaelax
DBPro Master
21
Years of Service
User Offline
Joined: 16th Apr 2003
Location: Metropia
Posted: 24th May 2013 04:09
Link
So why don't one of you create the wiki and get it started? Documentation for a language can require a lot of work, so I'm not surprised there are a few mistakes or some missing pieces.

Quote: "If a wiki would not provide this, it would not be the fault of the wiki, it would be the fault of the writers."

Maybe you can explain to me how a wiki differs from just having the help files online? I'm not a huge wiki fan either, but it sounds like you have a different idea than what I'm thinking a wiki is like.

"You're all wrong. You're all idiots." ~Fluffy Rabbit
Back to top
Profile PM Email Website
AgentSam
12
Years of Service
User Offline
Joined: 14th Mar 2012
Location: Virtual Space
Posted: 24th May 2013 04:23
Link
Phealax,

Take a look at what's been happening in the past... I tried to provide a small glimpse of that history in my post earlier.

None of the attemps to get an "AGK Community Wiki" accepted have been very successful.

It is not so much a problem in creating the wiki, as it is in getting the "OFFICIAL STAMP OF APPROVAL" on it.

It needs to be BY TGC - with the full support of TGC. The "full support" does not mean a lot of additional work, but just making it the primary official AppGameKit doc site.

Without the official seal, and the direct support by TGC, the AppGameKit documentation wiki will fail.

Why? Because unless it IS the primary doc site, it will become a "secondary" doc site as soon as TGC updates the primary site. (It's impossible to not see this pattern.)

I also do not understand why the documentation efforts could NOT be concentrated. There is no point in you, Plealax, keeping a copy of the AppGameKit docs on your site, while the AppGameKit Community has another, and the Official AppGameKit 108.12 distro has a third.

I hope this somewhat clarifies where I see the problem.

Cheers,
AgentSam
Back to top
Profile PM
AgentSam
12
Years of Service
User Offline
Joined: 14th Mar 2012
Location: Virtual Space
Posted: 24th May 2013 04:41 Edited at: 24th May 2013 04:56
Link
Quote: "it sounds like you have a different idea than what I'm thinking a wiki is"


What do you think a wiki is ?

Quote: "explain to me how a wiki differs from just having the help files online?"


Review this question, by starting from the assumption that TGC wants document writers from the user community to edit the help docs, for starters. Now, do you see how a wiki might be better than static files that are "just online"?

Cheers,
AgentSam

I think I'm going to just throw my arms in the air and shrug off any idealistic hopes that people would have understood what the heck it is I was talking about. My failure possibly.
Back to top
Profile PM
Phaelax
DBPro Master
21
Years of Service
User Offline
Joined: 16th Apr 2003
Location: Metropia
Posted: 24th May 2013 05:06 Edited at: 24th May 2013 05:07
Link
So you want a shared/synced repository of user-edited docs?

I only made mine yesterday morning because I wasn't aware there was any other online system already in place. I know there were some concerns about various command explanations and I was going to try and write better ones myself. But I see your point.

I'm not familiar with how all wiki works. Is it just open to whoever to edit the content or is there a central person who authorizes each update?

"You're all wrong. You're all idiots." ~Fluffy Rabbit
Back to top
Profile PM Email Website
Back to top

Login to post a reply

Server time is: 2024-05-04 10:30:20
Your offset time is: 2024-05-04 10:30:20