New Quick Start Guide

[tajmone]

@AnssiR66, I've created the temporary dev-QuickStart branch for working on the Quick Start Guide.

I've ported the original text to AsciiDoc and formatted it, but the guide seems very old and in need of being updated. So I've added to the text various admonitions with suggestions, notes on the problems that need to be addressed, and the various TODOs.

I'd like your feedback on my annotations, and suggestions on how to update this guide for the new library release.

For the duration of the temporary dev branch, the latest version of the document will always be previewable at the following Live HTML link:

• lib_distro/docs/QuickStart.html

It's not a long guide, so we should be able to fix it within this week, two weeks at most. But I'd like to externalize the examples to real code, just to make sure that if they ever break due to changes to the library codebase we'll catch the errors immediately, and update the examples accordingly.

In general, I'd like to keep the original spirit of the guide, and just make a few adjustments to take advantage of recent changes, new assets, etc., so that the reader can get the most out of the package and start an adventure with minimum efforts.

[AnssiR66]

The updated version of the QuickStart quide looks fine, I would just ask/discuss - is the newgame.alan template necessary to write a new ALAN game, can't it just be a helpful "aid" but not an obligatory one?

[tajmone]

The updated version of the QuickStart quide looks fine

Sorry if I haven't carried on with it but in these days I've been unable to work at the PC due to family problems. Hopefully in a week time things should be back to normal.

... is the newgame.alan template necessary to write a new ALAN game, can't it just be a helpful "aid" but not an obligatory one?

I personally use it for every game, including our test adventures here in the repository. Well, not the template file directly, but rather an editor "snippet" for Sublime Text which I've modeled around the original template file (the difference being that it has preset values and tab-stops to cycle through the various entries, which allows a very quick setup).

So, I'd say that this template file is important, whether end users use as it is or build a custom snippet for their favorite editor.

As for the "Quick Start Guide", I think that using the template as a reference and starting point makes sense, since the template is part of the package, and the guide can illustrate what's what in it.

Of course, that's for absolute beginners, so whether advanced users will carry on using the newgame.alan template or simply type the boilerplate by hand, or convert newgame.alan into a snippet for their editor, well that's up to the individual end user.

I think that boilerplate templates are useful, and that keeping newgame.alan as part of the package is also a good mean to ensure that in case future updates introduce breaking changes end users will always have a boilerplate to start with (in case these changes affect core elements such as the DEFINITION_BLOCK, the name of my_game or the banner, you never know).

Since I always update my editor snippet based on the latest version of the newgame.alan file, and that I use that boilerplate snippet to create all new library tests and examples, we don't have to worry about its maintenance and checking that it's always up to date, since it's being used (albeit in an indirect manner). But I was planning to also add a small integrity check for newgame.alan in the Rakefile — the template should compile without error as it is, since it contains all the minimum requirements for an adventure.

In fact, while working on the Quick Start guide, I've realized that it contained a small typo (a missing . after the first line of the definition of the start location), something that I must have fixed in my snippet but not in the original file at the time (this was before I was contributing to the StdLib, and the template hasn't been changed since).

If you prefer that the "Quick Start" guide doesn't use the newgame.alan template, but rather shows how to code the required elements by hand (instead of showing how to tweak the template presets) it's fine with me. In that case, though, we'll have to add a small guide on how to use the template file somewhere (since I've removed the comments form it in the dev branch, thinking that Quick Start guide would make them unnecessary).

Basically, the change here is that before newgame.alan contained self-explanatory comments on how to use it, whereas now I've removed them and thought of using the Quick Start guide to teach how to use it. The rationale is that such comments in the boilerplate soon become cumbersome, since there's more work deleting them than tweaking the preset values, and users will no longer need those comments after a couple of adventures.