New Library Design Documentation

[tajmone]

@thoni56, I've added to the dev_alan-en branch an AsciiDoc document on the Foundation Library Design, inside alan_en/docs/:

• library-design.asciidoc

The general idea is:

• Having a reference document make all discussions easier, since we can always check its status, instead of having to sift through all the various discussion, which might be outdated (unlike the doc, which should always mirror our latest decisions, and changes of heart too).
• The latest version of the doc will always be found in the dev_alan-en branch, since the English library is the reference implementation, and the document is still WIP.
• I'm adding ideas to it (including question and pending tasks lists) as they come to my mind, and everyone is free to alter the document according to his thoughts and proposal (after all it's all a WIP draft right now).
• Sometimes I mention that the library does this or that even though the code hasn't been changed to that, but I'm planning to it soon.
• The Design doc and the library code will influence each other's development as we go along. E.g. I might write down an idea in the Doc, but later on during its implementation and testing might realize there's a better solution or it simply doesn't work as well as imagined, etc. Also, studying the original library code often prompts questions which are worth annotating in the Doc.

I'm not tracking the HTML document in the repository, but Rake automagically updates it for us, so it should always be available locally (right now, there's no syntax highlighting, custom themes or other fancy stuff, I'll add that later on, when approaching v1.0.0).

We can discuss in thread any design topics which are worth mentioning and adding to the Design Doc, and then if there are some topics which deserve careful consideration we can create a separate discussion for them (like we did with the wearing mechanics).

Feel free to jot down into AsciiDoc source any design ideas, questions, and chapters titles which come to your mind — I'll see them when I pull the branch for updates. This could be a sort of "background communication", where ideas are written directly in the doc, and then further discussed here.

[thoni56]

This sounds like a good idea.