New Dev Docs

[tajmone]

I've now created a new dev-docs/ folder dedicated to library developers and porters.

Foundation Library Design Book

Currently it contains only the Foundation Library Design document, found in dev-docs/design/, which at the moment is almost identical to the original English library documentation.

In the course of time, the book will grow in technical details covering the library design choices, technical implementation details, porting guidelines, etc.

While working on the library sources I've noticed many implementation detail which I can't figure out why they were chosen; since the original code base dates back to almost two decades (the library was initially written for ALAN 2) probably the rationales behind these design choices have been lost to oblivion a long time ago.

Since we have no way to determine whether some choices were due to the constraints of the ALAN language at that time (constraints which might have been lifted through new features), we should probably start questioning the whole design from scratch — from asking whether we want to implement multi-parameters for some verbs, up to the parameters naming convention, and any other design choice that will impact end users.

This time, we'll annotate each and every design choice in the Foundation Library Design document, so posterity won't end up having to guess why the library was written the way it is.

In the meantime, we'll be using the repository Discussions to evaluate the pros and cons of each design choice, adding to the Foundation Library Design document admonitions blocks linking to the various discussion which are still open and undecided.

Libraries User Guides

The idea is to now keep the documents within the library implementations as their end users' Guide, without dealing with developers' specific technical aspects. This also means that it makes sense to write each user guide in the locale of the library (Italian, Spanish, Swedish, etc.).

At the moment, only the Spanish library hosts a docs/ subfolder, although it has been written in English so far.

@Rich15, how's your experience with the AsciiDoc format? Would you feel confident enough to work on the AsciiDoc sources to write the Spanish Foundation User Guide in Spanish? or would you rather prefer to carry on writing it in English, and then translate it to Spanish when version 1.0.0 of the library is approaching, using the English source code as a reference track to work on top of?

I might be adding the user guide to the Italian library soon, so you might also use that as a reference.

In any case, right now there's no hurry to focus on any of the users' guide, since the library is still undergoing lots of changes. Nevertheless, as some features get agreed on and implemented, I'll try to document them (in the English library at least).

The English user guide should probably serve as the reference document for the other libraries too, with the exception of the language specific additions (like gender and number, etc.), but the overall skeleton of the Guide should be the same more or less.

Upcoming Dev Docs

I was also planning to add two more developers docs, sometime in the nearby future:

1. Cloak Guide — a document describing how the Cloak of Darkness_ sample adventure should be implemented using the Foundation Library, since every library implementation should contain the Cloak demo.
2. Vampiro Guide — a document describing how the Vampiro sample should be implemented using Foundation. Like for Cloak, it would be nice (but not mandatory) if every library could also provide an implementation of the Vampiro adventure, which is closer to a full adventure than the small Cloak sample.