Documentation - the module designer's guide

Module Design
1

I have found two things in the Developer’s Guide that seem to be wrong or out of date.

  1. On page 77 the section on Deck Global Key Command mentions a “Keyboard Command”. However it is not in the accompanying image nor can I find it in the module editor.

  2. On page 42 the section on Keyboard Shortcuts does not mention that you may use meaningful text instead of a combination of keys. Also it does not explain how you actually enter keys. This may be obvious but you cannot paste in the text from elsewhere because then you just set it to “Ctrl-V”.

I have had a break from VASSAL editing for a while, and now I am coming back the dissonance seems stronger.

2

The Designer’s Guide is horribly out-of-date: see recent discussion here: Reference Manual vs. Designer's Guide

1 Like
3

Ah Thanks. I had forgotten about the reference manual. You see I have forgotten a random 50% of what I knew.

That said the reference manual still says that there is a " Keyboard command" field when there isn’t.

4

The version of the reference manual on the wiki is also horribly out-of-date, unfortunately. The latest version is in the doc subdirectory of your VASSAL installation (these are the same HTML files that are opened when you click a Help button within VASSAL itself). However, Brent just finished a major overhaul of the Reference Manual, and I don’t think it made it into 3.6 Beta 1–it will only be in more recent builds.

Edit: Just checked the Reference Manual included with 3.6 Beta 1, and that Keyboard Command field is not listed, so that was probably fixed years ago.

5

One of the following things needs to happen:

  • The reference manual is removed from the wiki.
  • The HTML-based reference manual is removed.
  • One of them is generated from the other.

It’s duplicated effort keeping them both current, and it’s confusing for users when one of them inevitably is out of date.

6

I can’t find the pdf reference manual on the wiki so may be that has happened already.

With regards to the Wiki reference manual, surely a wiki is the wrong way to go. Surely the build process should just copy the documentation to a directory in the web page structure.

There may also be a way of generating a pdf from an HTML directory.

7

We thought that a wiki would be a low-friction way of getting advanced users to help produce documentation. That didn’t happen, and I don’t know why not.

That would be what we’d want if we removed the docs from the wiki, yeah.

8

For the moment, I’ve added a warning text box to the wiki Reference Manual directing users to look at the copy in their VASSAL installation, instead (the edit is pending review, of course).

1 Like