Author Topic: Improving AGS manual  (Read 5847 times)

Crimson Wizard

  • Local Moderator
    • Best Innovation Award Winner 2013, for spearheading the AGS 3.3.0 project
    • Lifetime Achievement Award Winner
    • Crimson Wizard worked on a game that won an AGS Award!
    •  
    • Crimson Wizard worked on a game that was nominated for an AGS Award!
Improving AGS manual
« on: 26 Jul 2012, 08:36 »
Are there any plans to improve the manual?

Personally I think it lacks distinct topics on using certain parts of editor. For example, there's no "Room Editor" or "Properties Pane" topics, these are described only in tutorials, which is not really good in my opinion. I remember that caused great confusion for me when I just started to use AGS (I couldn't figure out where to look for information).

Also, I noticed that beginners keep asking same questions about most basic behavior over time. It means that either some information is missing or explained not well enough.
What about searching through Technical board and gather FAQ? It may later be used to improve existing topics, remake FAQ section, or, perhaps, add new HOWTO section in the manual that would cover tips on implementing most desired non-basic game features.


BTW, online manual still describes AGS 2.72 in Tutorial section.

EDIT: maybe I should have posted this in Adventure Related talk board to bring more attention? :)
« Last Edit: 26 Jul 2012, 15:25 by Crimson Wizard »

Tabata

  • mouse-fetishist & smiley-maniac
Re: Improving AGS manual
« Reply #1 on: 26 Jul 2012, 17:15 »
I think improving the manual is necessary, too!   
I'd appreciate an easy to use version (current and with a working search function).  (roll)

It's kind of the bible for people around here and it should get proper attention and care. 

Snarky

  • Global Moderator
  • Private Insultant
    • I can help with proof reading
    • I can help with translating
Re: Improving AGS manual
« Reply #2 on: 26 Jul 2012, 17:22 »
If I could find the time, I'd be happy to work on improving the manual.

What's wrong with the search function?

Tabata

  • mouse-fetishist & smiley-maniac
Re: Improving AGS manual
« Reply #3 on: 27 Jul 2012, 06:16 »
For example the knoledge base.
Not that I don't like her, but she comes up for every search term you type in,
telling me that the page doesn't exist :confused:
               

Snarky

  • Global Moderator
  • Private Insultant
    • I can help with proof reading
    • I can help with translating
Re: Improving AGS manual
« Reply #4 on: 27 Jul 2012, 07:48 »
Ah, but the knowledge base isn't the manual. And I thought we were talking about the one that comes with AGS, anyway. Someone already made a better version (as in: a closer match to the offline version) of the online manual; it just hasn't been added to the site.

I don't see the point of the knowledge base, and think it should be eliminated (most of the articles seem terribly out of date) or integrated into the actual manual.

Crimson Wizard

  • Local Moderator
    • Best Innovation Award Winner 2013, for spearheading the AGS 3.3.0 project
    • Lifetime Achievement Award Winner
    • Crimson Wizard worked on a game that won an AGS Award!
    •  
    • Crimson Wizard worked on a game that was nominated for an AGS Award!
Re: Improving AGS manual
« Reply #5 on: 27 Jul 2012, 08:18 »
Since CHM is made of html pages, wouldn't that be possible to update both online and offline version simultaneously by maintaining a shared bunch of pages that would be copied both to site and repository? Unless there will be any problems with relative links or something.

AGA

  • Adventure Game Aficionado
  • Administrator
  • ¡Qué alí­vio!
    • Lifetime Achievement Award Winner
    • AGA worked on a game that was nominated for an AGS Award!
Re: Improving AGS manual
« Reply #6 on: 27 Jul 2012, 09:45 »
Since CHM is made of html pages, wouldn't that be possible to update both online and offline version simultaneously by maintaining a shared bunch of pages that would be copied both to site and repository? Unless there will be any problems with relative links or something.

Is this not what this thread is about?

Snarky

  • Global Moderator
  • Private Insultant
    • I can help with proof reading
    • I can help with translating
Re: Improving AGS manual
« Reply #7 on: 27 Jul 2012, 11:06 »
Can you just switch out the current online manual for the build that Mr. Ouxx made, AGA?


AGA

  • Adventure Game Aficionado
  • Administrator
  • ¡Qué alí­vio!
    • Lifetime Achievement Award Winner
    • AGA worked on a game that was nominated for an AGS Award!
Re: Improving AGS manual
« Reply #9 on: 01 Aug 2012, 09:37 »
Can you just switch out the current online manual for the build that Mr. Ouxx made, AGA?

Unfortunately the new site design is compiled aspx, which means I can't easily go in and change stuff like links to the manual.  I'll poke CJ again about giving me the source files so I can.

Crimson Wizard

  • Local Moderator
    • Best Innovation Award Winner 2013, for spearheading the AGS 3.3.0 project
    • Lifetime Achievement Award Winner
    • Crimson Wizard worked on a game that won an AGS Award!
    •  
    • Crimson Wizard worked on a game that was nominated for an AGS Award!
Re: Improving AGS manual
« Reply #10 on: 02 Aug 2012, 20:41 »
NickyNice sent me this in PM, I hope he won't mind if I repost his thought here:

Here's something as a noob that made it tough to find certain things...

If you hit F1 in the editor and type in Walkable area, it doesn't pop up under W. Obviously you need to look under R for RemoveWalkableArea.

I think as a noob (ME), this sometimes makes things tough to find. There's a few other cases too, but I'm brain dead at the moment. As a noob it's tough to find those key words like...Remove. You have disable, remove and a few words like these that come before the actual word you're looking for. Once you learn it, it's not that big of a deal really, but that's what tripped me up a bit back in the day. Maybe if you guys add walkable area to the index and have that branch off to all the walkable area possibilities in the manual  :-\  you could leave the remove walkable area section where it is too.

Also this:
http://www.adventuregamestudio.co.uk/yabb/index.php?topic=46530.msg625964#msg625964
« Last Edit: 02 Aug 2012, 21:14 by Crimson Wizard »

Crimson Wizard

  • Local Moderator
    • Best Innovation Award Winner 2013, for spearheading the AGS 3.3.0 project
    • Lifetime Achievement Award Winner
    • Crimson Wizard worked on a game that won an AGS Award!
    •  
    • Crimson Wizard worked on a game that was nominated for an AGS Award!
Re: Improving AGS manual
« Reply #11 on: 21 Jan 2013, 07:28 »
It appears that compiled offline manual includes an older version of "Tutorials" index, linked from the Part 9 Tutorial ("Cursors"). This older page version also has links to non-existing pages: "Introduction to scripting" and "GUI Scripting Part 1 - Making a custom Quit GUI".

Related discussion here: http://www.adventuregamestudio.co.uk/forums/index.php?topic=47482.msg636444187#msg636444187

Billbis

  • R, what else?
    • I can help with translating
Re: Improving AGS manual
« Reply #12 on: 24 Jan 2013, 20:40 »
I am a bit confuse by the different SaveGameSlots that exist, and how they are explain in AGS manual:
Quote from: SaveGameSlot
The SaveGameDialog function uses slots numbered from 1 to 20, so if you don't want to interfere with the player's saves, I would recommend saving to slot numbers of 100 and above.
Quote from: DeleteSaveSlot
NOTE: if you specify one of the standard slots (1-50), then AGS will rearrange the other save games to make sure there is a sequence of slots from 1 upwards. Therefore, you will need to refresh any save game lists you have after calling this function.
How many SaveGameSlot categories there is ? 1 - 20, 21 - 50, 51 - 100 and 101 - infinite? What are there respective properties? Seems very unclear to me.

monkey0506

  • SEND PIZZA.
    • Best Innovation Award Winner 2017, for his work to help AGS games reach the widest possible audience - through popular distribution platforms (Steam, Galaxy) as well as other operating systems (Android, Linux)
Re: Improving AGS manual
« Reply #13 on: 07 Feb 2013, 21:52 »
I believe that the engine itself will now use 50 as the "standard" slots (the ones that can be populated by ListBox.FillSaveGameList), but you should be able to save up to at least 998 unique slots from 1-998. Slot 999 is reserved by the engine for the reset game position. I'm not certain that slot numbers 1000+ are valid. I agree that this is one of the entries that was unfortunately not properly maintained. The best route (IMO) would be to stop relying on static maximums and have FillSaveGameList and other associated functions work directly on the existing save files instead.

Crimson Wizard

  • Local Moderator
    • Best Innovation Award Winner 2013, for spearheading the AGS 3.3.0 project
    • Lifetime Achievement Award Winner
    • Crimson Wizard worked on a game that won an AGS Award!
    •  
    • Crimson Wizard worked on a game that was nominated for an AGS Award!
Re: Improving AGS manual
« Reply #14 on: 06 Mar 2013, 07:54 »
It appears, the /* */ comment style is not mentioned in the manual. At least not in Scripting Tutorial 1, where the '//' comment style is explained.

Slasher

  • slasher
    • I can help with AGS tutoring
    • Lifetime Achievement Award Winner
    • I can help with scripting
    • I can help with story design
    • Slasher worked on a game that was nominated for an AGS Award!
Re: Improving AGS manual
« Reply #15 on: 06 Mar 2013, 11:04 »
While we're on comments (Crimson)

Multi-lined comments, like in html comments.

Crimson Wizard

  • Local Moderator
    • Best Innovation Award Winner 2013, for spearheading the AGS 3.3.0 project
    • Lifetime Achievement Award Winner
    • Crimson Wizard worked on a game that won an AGS Award!
    •  
    • Crimson Wizard worked on a game that was nominated for an AGS Award!
Re: Improving AGS manual
« Reply #16 on: 06 Mar 2013, 11:09 »
Multi-lined comments, like in html comments.

What?   ???

Gilbert

  • * KILL* * KILL * * KILL *
    • Lifetime Achievement Award Winner
Re: Improving AGS manual
« Reply #17 on: 06 Mar 2013, 15:25 »
Multi-lined comments.
The /* */ thing that Crimson mentioned IS multi-lined comments.  :tongue:
It's always been there and I'm using it since ages. It's just not clearly documented.

Re: Improving AGS manual
« Reply #18 on: 06 Mar 2013, 16:48 »
I'm also confused. Maybe he asked for HTML-style comments? The ones that are written this way <!-- comment --> :confused:

Cerno

  • Animating kills me
Re: Improving AGS manual
« Reply #19 on: 09 Mar 2013, 10:22 »
As a beginner who fell into more than one trap that were not addressed by the manual, I wholeheartedly agree and since I am currently trying to write a game and assume I will continue to misstep like any beginner, I would like to offer contributing to the manual as well (if I find the time).

To me I think that many entries in the manual are well-written, but do not allow for further reading to get an impression on what works and what doesn't. I recently posted a question about some narrator behavior which I found strange (why in LucasArts mode does the narrator speak in the player's voice?). It could have prevented some headaches if the manual stated that there are different interpretations of the narrator (LucasArts vs. Sierra), followed by a description what to expect in which style.

Personally, I think the manual would benefit from being more verbose in places, but maybe it might be a good idea to organize everything so that the beginner is not slain by a wall of text while the ones in search for more detail find it. I also think it would benefit the help system to include "best practice" entries with code examples, possibly on separate pages to prevent spamming the manual with code snippets. Using my narrator example from above, I received a very helpful solution (use an invisible narrator) together with code snippets that showed how to implement this. Of course it needs to be decided which solutions are important enough to go in the manual and which are just solutions for corner cases. Maybe having a link collection to the forum for certain topics might be a good idea?

A minor issue is that often the manual links to deprecated scripting code. I think this might be improved by adding a section for "deprecated items:" to separate it from the regular "see also" links. Alternatively you could even get rid of links to deprecated code (depending on the rationale behind these links in the first place).

A thought about how to work on improving the manual: While I think a collaborative system like a Wiki would be perfect to allow many people to contribute, there definitely needs to be a moderating instance that decides what goes into the final manual and what not. So would we find a way to collect suggestions in a Wiki that are then rewritten for the manual? On the other hand, synchronizing that information would be quite troublesome I guess.

So these are my thoughts. I would like to contribute my beginner's experience if you like. Is there a place to put this at this time or should I just append it to this thread?

Cheers
Cerno
  Currently working on: Sibun - Shadow of the Septemplicon