Mittens 2018 will be in Boston this September. There are three spaces left, so check out the thread for details!

Author Topic: Help file... here we go again.  (Read 7921 times)

Crimson Wizard

  • Local Moderator
  • AGS Project Tracker Admins
    • Best Innovation Award Winner 2013, for spearheading the AGS 3.3.0 project
    •  
    • Lifetime Achievement Award Winner
    •  
    • Crimson Wizard worked on a game that was nominated for an AGS Award!
      Crimson Wizard worked on a game that won an AGS Award!
Re: Help file... here we go again.
« Reply #20 on: 03 Jul 2016, 09:29 »
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.
« Last Edit: 03 Jul 2016, 10:38 by Crimson Wizard »

Re: Help file... here we go again.
« Reply #21 on: 03 Jul 2016, 10:50 »
I can help.  I think it might be a good idea to just throw away all formats and host the documentation on https://readthedocs.org/ .  It automatically builds docs for restructuredtext/markdown. This would mean resurrecting the doc pull request that converts all documentation to rST.

It would be worth finding out if people need documentation. Something that's google-able would be helpful for newcomers.

Crimson Wizard

  • Local Moderator
  • AGS Project Tracker Admins
    • Best Innovation Award Winner 2013, for spearheading the AGS 3.3.0 project
    •  
    • Lifetime Achievement Award Winner
    •  
    • Crimson Wizard worked on a game that was nominated for an AGS Award!
      Crimson Wizard worked on a game that won an AGS Award!
Re: Help file... here we go again.
« Reply #22 on: 03 Jul 2016, 23:00 »
Nick, this reply of yours is pretty confusing.

I think it might be a good idea to just throw away all formats and host the documentation on https://readthedocs.org/
<...>
It would be worth finding out if people need documentation.
Do you mean -  throw away help file (offline documentation)? Basically, you suggest to convert manual to RST, and then use it to create online documentation?

I would not like to disband offline docs. Imagine a person goes somewhere with no internet connection (or bad connection), and want to continue working on game.
Unless that site allows to download docs (in which form?)...
« Last Edit: 03 Jul 2016, 23:07 by Crimson Wizard »

selmiak

  • ǝsıɔɹǝxǝ ʞɔǝu puɐ uıɐɹq
    • I can help with play testing
    •  
    • I can help with proof reading
    •  
    • I can help with translating
    •  
    • I can help with web design
    •  
    • selmiak worked on a game that was nominated for an AGS Award!
Re: Help file... here we go again.
« Reply #23 on: 05 Jul 2016, 23:49 »
I have an idea. tell me what you think.

we make a new separate wiki only for the manual on the ags server. everyone with an forum account can edit it, just like the normal AGS wiki. This new wiki is only for the manual, the manual wiki so to say. Or the wiki manual, whatever you prefer and gets used the most I think.
Then with some code magic we strap the complete content, the topics of the articles and the links and convert this content from the wiki to some (html) format the helpdisplay in ags and windows can display. grab what is on that manual wiki and make ags help display this.
At the beginning it will be empty like every wiki so we should first fill it. we should gather some 5-10 or even more people to at first transfer the current manual to the wiki. everyone get one letter, check this letter, then the next one, the more people help converting the old manual content to wiki format the faster this will happen.
Then we can add new topics for new functions over time and it will always be up to date in the wiki manual already. We could even have some cronjob on the server to gather the new wiki pages and pack it to the ags distribution files. I think it is close to impossible to add some malicious code to wiki markup that will break out from the helpdisplay sandbox and screw with users computers.

almost everyone can write wiki markup and if not, it is very easy to pick up, tech savvy people like the forum users that want to help write the technical manual will get into it in no time. The easier the pages are to edit to more people can help and the faster things get done in that scale.

so my conclusion for this idea is to find some code wizard that can or thinks he can convert some wiki markup to some helpfile display content. he or she shall chose the wiki software and the help file display software and get coding. once this code works we only need to fill the wiki and voila.
« Last Edit: 05 Jul 2016, 23:52 by selmiak »

Crimson Wizard

  • Local Moderator
  • AGS Project Tracker Admins
    • Best Innovation Award Winner 2013, for spearheading the AGS 3.3.0 project
    •  
    • Lifetime Achievement Award Winner
    •  
    • Crimson Wizard worked on a game that was nominated for an AGS Award!
      Crimson Wizard worked on a game that won an AGS Award!
Re: Help file... here we go again.
« Reply #24 on: 06 Jul 2016, 02:21 »
so my conclusion for this idea is to find some code wizard that can or thinks he can convert some wiki markup to some helpfile display content. he or she shall chose the wiki software and the help file display software and get coding.

There is certainly software that does this. Recently I found one: http://pandoc.org/

Gurok

  • Rottwheelers
  • When life hands you lemons, combine them with the mop
    • I can help with AGS tutoring
    •  
    • Best Innovation Award Winner 2016, for improving and extending the AGS scripting language
    •  
    • I can help with proof reading
    •  
    • I can help with scripting
    •  
    • Gurok worked on a game that was nominated for an AGS Award!
      Gurok worked on a game that won an AGS Award!
Re: Help file... here we go again.
« Reply #25 on: 06 Jul 2016, 02:36 »
I would not like to disband offline docs. Imagine a person goes somewhere with no internet connection (or bad connection), and want to continue working on game.
Unless that site allows to download docs (in which form?)...

Agree completely. This might also be an intentional thing, e.g. Someone might go somewhere remote to get away from the Internet and write their game. Actually, that sounds like a rather nice idea for a holiday, come to think of it.

so my conclusion for this idea is to find some code wizard that can or thinks he can convert some wiki markup to some helpfile display content. he or she shall chose the wiki software and the help file display software and get coding.

There is certainly software that does this. Recently I found one: http://pandoc.org/

I saw you mention this on GitHub too and I just want to clarify.

Was your suggestion to use Pandoc to go from some Wiki->rST and then Sphinx2 (as currently nominated on GitHub) to go from rST->CHM?

It's unfortunate that CHM output doesn't seem to be a priority for the Pandoc people:
https://github.com/jgm/pandoc/issues/2056

Crimson Wizard

  • Local Moderator
  • AGS Project Tracker Admins
    • Best Innovation Award Winner 2013, for spearheading the AGS 3.3.0 project
    •  
    • Lifetime Achievement Award Winner
    •  
    • Crimson Wizard worked on a game that was nominated for an AGS Award!
      Crimson Wizard worked on a game that won an AGS Award!
Re: Help file... here we go again.
« Reply #26 on: 06 Jul 2016, 02:51 »
This might also be an intentional thing, e.g. Someone might go somewhere remote to get away from the Internet and write their game. Actually, that sounds like a rather nice idea for a holiday, come to think of it.
Haha, my thoughts exactly.
I saw you mention this on GitHub too and I just want to clarify.

Was your suggestion to use Pandoc to go from some Wiki->rST and then Sphinx2 (as currently nominated on GitHub) to go from rST->CHM?

It's unfortunate that CHM output doesn't seem to be a priority for the Pandoc people:
https://github.com/jgm/pandoc/issues/2056

No, my suggestion on github was to use Pandoc to convert LaTeX to rST (both are source formats).

We apparently do not need to use Pandoc to get CHM from rST: http://www.adventuregamestudio.co.uk/forums/index.php?topic=51340.msg636501803#msg636501803
Sphynx builds HTML Help project from rST, and Microsoft's own "hhc" utility compiles CHM.
If Pandoc could convert to HTML Help too, it could be used in the same process (although that is not the main point).

Also, we were wanting to get rid of CHM altogether. It is just that we may have to keep it for some time (if solving the issues step by step).

The remaining question is just which (offline) help viewer to use instead of CHM.
« Last Edit: 06 Jul 2016, 03:03 by Crimson Wizard »

Re: Help file... here we go again.
« Reply #27 on: 06 Jul 2016, 04:05 »
Pandoc's a document converter but it wouldn't be the final step. You'd still need a document tool like Sphinx to create offline documentation for chm.

I'm not sure the wiki is a great idea. You still want to have documentation tied to your particular branch in the AGS repository.  How would the wiki treat documentation that would be different for stable and development branches?

However there is something to be said for making it easier to contribute.

Picking a different markup language for the manual would be a good first step. Despite RestructuredText possibly being better suited for documentation, I think a lot of major projects are using Markdown for documentation because more people are familiar with it and that lowers the barrier for people to contribute. Even Microsoft has started using it for some of their github backed docs.

Github allows people to fork repository, edit files and create pull requests all within the browser. That is almost a wiki-like experience but with better change controls.

Nick.

Re: Help file... here we go again.
« Reply #28 on: 23 Jul 2016, 07:27 »
I would suggest to first define what you want from documentation, then consider the format and place of the source, then consider how to get there from what you have now.

"what you want" would include
- online/offline (both I think)
- purpose of the documentation (what does it contain, what can you learn from it)
- up-to-date-ness of the documentation (how bad is it if it runs behind a year or more)
- users of the documentation
- editors of the documentation (who for what parts mostly)
- try to come up with more properties that you desire from the documentation

Crimson Wizard

  • Local Moderator
  • AGS Project Tracker Admins
    • Best Innovation Award Winner 2013, for spearheading the AGS 3.3.0 project
    •  
    • Lifetime Achievement Award Winner
    •  
    • Crimson Wizard worked on a game that was nominated for an AGS Award!
      Crimson Wizard worked on a game that won an AGS Award!
Re: Help file... here we go again.
« Reply #29 on: 13 Dec 2016, 23:29 »
Ok... I will give this another try.

I would suggest to first define what you want from documentation, then consider the format and place of the source, then consider how to get there from what you have now.

Quote
- online/offline (both I think)
Yes, both, because it would be more comfortable to know that people can use documentation even without internet connection. Of course format could be same (like, you can view html pages from your HDD too).

Quote
- purpose of the documentation (what does it contain, what can you learn from it)
Priority is given to end-user documentation for AGS Editor and engine.
For AGS Editor, ideally, documentation should include sufficient information for a person who first met AGS to create and deploy games in it: feature overviews, explanation of workflow, detailed each window description, basic tutorials, and of course script API reference.
For the engine - at least the basic information on its work from the game-dev and player's perspective: (games) installation requirements, paths and files it uses, manual configuration, command-line arguments.

Quote
- up-to-date-ness of the documentation (how bad is it if it runs behind a year or more)
It should be up-to-date with the latest official final (non-beta) release.

Quote
- users of the documentation
For AGS Editor documentation: game developers,
For engine end-user documentation: game developers and players (because the former should be able to reference something for the latter).

Quote
- editors of the documentation (who for what parts mostly)
Program developers must be able to update documentation when new release is out (script API, features).
Any other volunteer should be given a chance to contribute anytime whenever they think some articles needs improvement of corrections.
In simple case, program developer writes basic articles, and contributors help to fill in the gaps. (Not every programmer can write good tutorial)

Quote
- try to come up with more properties that you desire from the documentation
Offline docs should be browseable on most platforms (not something Windows-only).
Index and Search functionality. Capability to display images. Basic formatting capabilities (tables, lists, etc).


Other points.
There should be single source (repository) shared for the online and offline documentation.
Offline docs may be same format as online one (if applicable), just installed on disk (e.g. html files).
Ideally an automation should be set up: online documentation is updated as soon as source is modified, and offline version is available for download from the host location. Respective version of offline docs are also included with the AGS Editor installer.

How to upgrade from old manual
Setting up simple format conversion, then tidying up manually.

What about organizing documentation parties: announce a "week of improving documentation" - gathering volunteers, then giving them articles to improve.
« Last Edit: 07 Jan 2017, 22:37 by Crimson Wizard »

Re: Help file... here we go again.
« Reply #30 on: 21 Jul 2017, 23:34 »
Hey,

I used to use pandoc and sphinx, I was passing on the AGS topics and this is the first thing I thought "I know how to automate this!"

I have a project here (it's slightly abandoned) that has a help file built from Markdown source: https://github.com/ericoporto/fgmk/tree/master/docs

I use pandoc to go from .md to .rst and sphinx to build my help files (QtHelp and html).

You can take a look at the generated html help here: http://ericoporto.github.io/fgmk/

Can someone point me the source files?

Crimson Wizard

  • Local Moderator
  • AGS Project Tracker Admins
    • Best Innovation Award Winner 2013, for spearheading the AGS 3.3.0 project
    •  
    • Lifetime Achievement Award Winner
    •  
    • Crimson Wizard worked on a game that was nominated for an AGS Award!
      Crimson Wizard worked on a game that won an AGS Award!
Re: Help file... here we go again.
« Reply #31 on: 22 Jul 2017, 02:02 »
Can someone point me the source files?

https://github.com/adventuregamestudio/ags/tree/master/Manual


EDIT: if you run "run.cmd" (you also need to have Python 2.7 installed), the HTML files are created as an intermediate output. These may be easier to use than source TEX file.
« Last Edit: 22 Jul 2017, 12:39 by Crimson Wizard »

Re: Help file... here we go again.
« Reply #32 on: 24 Jul 2017, 08:31 »
Since the CHM format was reverse engineered you can also get the HTML files from the CHM file, by extracting it with 7-zip.