It's sad that this endeavour just ended with nothing. I can make a guess that people were expecting me to do something, but I cannot do everything, and I had other priorities at a time. I actually hoped there would be a community work in this.
My natural question: is this actually still needed? The fact that no one tried to improve situation in about 1.5 years since the last talk looks like either everyone is waiting for someone to start, or no one really cares about this anymore(?).
I'd like to know following:
- is moving to another help system
still wanted?
- am I expected to do something about it? Because, frankly, most of the related tasks could be done by anyone, not just me.
My opinion all this time was that manual is simply lacking material. For example, there is almost no structured information on how Editor works (for example, in the form of per-task or per-window reference).
Speaking honestly, is there someone who will be ready to work on such articles? Because it was possible all this time to add them even without changing manual format.
Splitting the overall problem, there are following issues that may in theory be solved separately:
1. Lacking documentation and/or bad manual structure (articles organized in a way that makes it hard to find what you want). For example, Editor is never properly explained, sans the Tutorial, but Tutorial mentions only few things you need to know to make your first demo game.
How to solve? Someone should simply write the text. That's it.
2. Bad source format. The current source format of the manual is an old version of LaTeX, and all manual is written as one huge file. Also, personally I could not find a satisfactory (that would be at least intuitive) tool to edit the source, so I myself do that in a common text editor.
How to solve? Look around for better format (some were already suggested in the past: Sphynx, etc). Tell us how source is edited, are there good utilities for that (provide examples). After the format is decided, make a plan for converting current manual: design guidelines (consistent presentation, styles), write automatic conversion script (latter is done by savvy person).
3. Slightly (?) outdated end format. AGS Editor is distributed with the manual as a CHM file. CHM is outdated, and sometimes does not run properly on latest versions of Windows. For the least we may try to upgrade it to WinHelp 2.0. Since AFAIK both are created from HTML pages, it should not matter which source format was chosen, there will always be a way to compile manual source into what we want (source -> HTML -> CHM/WinHelp2/other).
After end format is confirmed, Editor should be "taught" to work with that format (to keep context help working). Latter will be done by programmers, so don't worry about it.
4. Manual is "hidden" from editing by most community members. What I mean is that its source is located inside the AGS code repository, which may be psychologically complicating (?). Besides, you need to know and use Git to commit any changes there. Is there a way to make editing process easy enough for any regular community member to add/fix material, like they may do with Wiki?
5. Online manual(s) are out of date. There are two online manuals on AGS server, one is this:
http://www.adventuregamestudio.co.uk/manual/ , and another is in the Wiki:
http://www.adventuregamestudio.co.uk/wiki/Contents_(manual)
First was updated 2 major versions ago (5 years old), second - 3 major versions (7 years old!).
Question one: is there really a need for the one in the Wiki? No one is updating it anyway.
Question two: is there a way to automate primary online manual update? I guess the answer mainly depends on how the manual editing itself is organized (points 2 and 4).
This is to outline the potential tasks.
To be honest, this is probably my last attempt to initiate this work. Seeing no one is interested makes me indifferent myself, and if such activity is not wanted, I will just focus on limited range of tasks I do and never return to this myself.