Improving AGS manual

Started by Crimson Wizard, Thu 26/07/2012 08:36:11

Previous topic - Next topic

Crimson Wizard

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? :)

Tabata

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

If I could find the time, I'd be happy to work on improving the manual.

What's wrong with the search function?

Tabata

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

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

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

Quote from: Crimson Wizard on Fri 27/07/2012 08:18: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

Can you just switch out the current online manual for the build that Mr. Ouxx made, AGA?


AGA

Quote from: Snarky on Fri 27/07/2012 11:06:01
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

#10
NickyNice sent me this in PM, I hope he won't mind if I repost his thought here:

Quote from: NickyNyce on Thu 02/08/2012 20:37:21
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

Crimson Wizard

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

I am a bit confuse by the different SaveGameSlots that exist, and how they are explain in AGS manual:
Quote from: SaveGameSlotThe 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: DeleteSaveSlotNOTE: 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

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

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

While we're on comments (Crimson)

Multi-lined comments, like in html comments.

Crimson Wizard

Quote from: slasher on Wed 06/03/2013 11:04:18
Multi-lined comments, like in html comments.

What?   ???

Gilbert

Quote from: slasher on Wed 06/03/2013 11:04:18
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.

DrJone.s

I'm also confused. Maybe he asked for HTML-style comments? The ones that are written this way <!-- comment --> :confused:

Cerno

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
123  Currently working on: Sibun - Shadow of the Septemplicon

SMF spam blocked by CleanTalk