Adventure Game Studio | Forums

AGS Development => Editor Development => Topic started by: Crimson Wizard on 26 Jul 2012, 08:36

Title: Improving AGS manual
Post by: Crimson Wizard 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? :)
Title: Re: Improving AGS manual
Post by: Tabata 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.  (http://www.smileyvault.com/albums/userpics/12962/smileyvault-happyyes.gif)
Title: Re: Improving AGS manual
Post by: Snarky 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?
Title: Re: Improving AGS manual
Post by: Tabata 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:
                (http://img407.imageshack.us/img407/4494/oooops.png)
Title: Re: Improving AGS manual
Post by: Snarky 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.
Title: Re: Improving AGS manual
Post by: Crimson Wizard 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.
Title: Re: Improving AGS manual
Post by: AGA 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 (http://www.adventuregamestudio.co.uk/yabb/index.php?topic=46223.0) is about?
Title: Re: Improving AGS manual
Post by: Snarky on 27 Jul 2012, 11:06
Can you just switch out the current online manual for the build that Mr. Ouxx made, AGA?
Title: Re: Improving AGS manual
Post by: Crimson Wizard on 30 Jul 2012, 15:20
http://www.adventuregamestudio.co.uk/yabb/index.php?topic=46490.msg625516
Title: Re: Improving AGS manual
Post by: AGA 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.
Title: Re: Improving AGS manual
Post by: Crimson Wizard 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
Title: Re: Improving AGS manual
Post by: Crimson Wizard 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
Title: Re: Improving AGS manual
Post by: Billbis 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.
Title: Re: Improving AGS manual
Post by: monkey0506 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.
Title: Re: Improving AGS manual
Post by: Crimson Wizard 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.
Title: Re: Improving AGS manual
Post by: Slasher on 06 Mar 2013, 11:04
While we're on comments (Crimson)

Multi-lined comments, like in html comments.
Title: Re: Improving AGS manual
Post by: Crimson Wizard on 06 Mar 2013, 11:09
Multi-lined comments, like in html comments.

What?   ???
Title: Re: Improving AGS manual
Post by: Gilbert 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.
Title: Re: Improving AGS manual
Post by: DrJone.s 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:
Title: Re: Improving AGS manual
Post by: Cerno 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
Title: Re: Improving AGS manual
Post by: Demicrusaius on 09 Mar 2013, 11:10
I, perhaps wrongly, was turned off initially by the demo game. Maybe it does address the capabilities and functions controlled by AGS, but I couldn't bring myself to play it very long. I'll look at it again though, if people feel it has educational potential.
Title: Re: Improving AGS manual
Post by: Crimson Wizard on 09 Mar 2013, 13:45
Quote from: Cerno
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?

Yes, that's what I started this thread for.
You may also use this tracker section (in which case you'll be the first person to post there :)):
http://www.adventuregamestudio.co.uk/forums/index.php?project=8


I, perhaps wrongly, was turned off initially by the demo game. Maybe it does address the capabilities and functions controlled by AGS, but I couldn't bring myself to play it very long. I'll look at it again though, if people feel it has educational potential.
To be frank, I did not like its look much too :-/.
I found "OpenQuest" more pleasing, although I have no idea if it is easy to start learning with:
http://www.adventuregamestudio.co.uk/site/games/game/945/
Title: Re: Improving AGS manual
Post by: Cerno on 09 Mar 2013, 14:02
Another example I would like to share from my beginner's experience, which caused me a great deal of head-scratching last night and resolved itself today with the help of the forums.

I wanted to create a cutscene in which a character walks to A, talks to another character, walks to B, picks up an item and exits the room.

There are different ways to do it. Some work, some don't.

The gist of it that in my opinion would greatly improve the manual:
This information comprises only a few lines at the right spots in the manual (keywords: "RunInteraction", "Dialogs", "Cutscenes"/"Introduction Sequences") and would have saved me a few hours of trying and pestering people on the forums ;)
Title: Re: Improving AGS manual
Post by: Cerno on 09 Mar 2013, 14:08
Yes, that's what I started this thread for.
You may also use this tracker section (in which case you'll be the first person to post there :)):
http://www.adventuregamestudio.co.uk/forums/index.php?project=8

So, let's get the ball rolling.
I'll be using the tracker for tangible cases and the forum for more general issues.
Title: Re: Improving AGS manual
Post by: selmiak on 14 Mar 2013, 00:51
just found this tracker and added something too.
Title: Re: Improving AGS manual
Post by: Crimson Wizard on 16 Mar 2014, 15:20
*bump*
Seeing as people are posting on bug tracker regarding incomplete/erroneous manual articles - maybe someone can work on this?
Title: Re: Improving AGS manual
Post by: cat on 16 Mar 2014, 16:42
How can I edit the manual?
Title: Re: Improving AGS manual
Post by: Crimson Wizard on 16 Mar 2014, 17:21
The source in on GitHub: https://github.com/adventuregamestudio/ags/blob/master/Manual/ags.tex. It's in TeX format.
Although I believe that it will be more beneficial to invent a new help system which would allow community to improve manual more easily.
http://www.adventuregamestudio.co.uk/forums/index.php?topic=46223.msg636481301#msg636481301
Title: Re: Improving AGS manual
Post by: cat on 16 Mar 2014, 18:42
Well, then it might be best to collect all issues in the bugtracker and apply when the new manual is decided on?