New Manual-Partitioning

[tajmone]

EDITED — these changes are now merged into the dev branch!

---

@AnssiR66, I've been reorganizing the StdLib Manual by subdividing it into Parts. For now, all the work is in a temporary branch, so we can decide if the new structure is a good idea, and if not just discard it.

You can preview it via the usual Live HTML Preview link:

• StdLib Man Live Preview

In practical terms, I thought that reorganizing the book into Parts would help us better balance its contents, and avoid those long titles too. Also, the intention is to guide the reader through the exploration of the library topic by topic, following its modular structure.

In reality, only a few chapters had to be moved around to obtain this, although some very long chapters will be split into smaller chapters, since they now cover different topics of a same Part.

Roughly, the new Structure is going to be like this:

• Introduction
• Part I: Getting Started
  • Using the Library — How to setup the working environment, AlanIDE, use the newgame.alan template and/or include the Library in custom adventures.
  • Library overview — a first general introduction showing the library files, describing what each one does, and what the library provides, in general terms, preparing the reader for the general picture of the chapters to come.
  • Adding a Banner — how to setup a custom banner, and a first introduction of the my_game instance.
  • Creating Synonyms.
  • Library Attributes — overview of the library defined attributes.
• Part II: Library Classes
  • Intro — an overview of the predefined classes, with summary descriptions.
  • Locations
  • Things
  • Actors
  • ... etc. ...
  • Restricted Actions
  • ... etc. ...
• Part III: Library Verbs
  • Intro — an overview of the predefined verbs, how they related to StdLib classes, etc.
  • [various verbs chapters ...]
• Part IV: Library Messages
  • Runtime Messages
  • Library Messages — i.e. "string attributes messages", presented in various sections.
• Appendices — extra topics:
  • Translating the Library.
  • Short Examples

This is the general idea, which is more or less what you'll see in the preview link — except that right now I've just shifted around the existing chapters, and didn't get as far as splitting them up as required.

Personally, I think that this structure is optimal when it comes to using the book as a reference guide, for it's easy to know were to find each topic. But, at the same time, it still makes a good first reading, for it's still a book that can be read from beginning to end (the Parts and Chapters are order by their importance in the learning steps, each following chapter benefiting from the previous ones).

Surely, this doesn't mean that we won't mention my_game attributes for verb responses in Part III, which is dedicated to verbs — of course we'll do, in order to clarify examples — but the in-depth presentation of these attributes will be dealt in Part IV: Library Messages, in the Library Messages chapter.

Of course, this is a very raw draft, so you'll need to imagine how it would be once finished, with each Part being divided in multiple chapters.

From a maintenance point of view, splitting such a big book into smaller chapter is much better, and more in the spirit of AsciiDoc publications. For the reader, it should be better to, because it offers a more balanced book structure.

Before going ahead, I'd like to know what you think of this new structure, if you like it and if you think it's going to be beneficial.

[tajmone]

Merged into Dev Branch!

@AnssiR66, I finally decided to merge the new structure based on some simple considerations:

1. The fact that you entrusted me to take decision on the updates.
2. The fact that only a few chapters have been actually moved around by the new system, some of which needed to be changed anyways due to the new library modules split introduced recently.
3. The use of Parts reduces the section numbering, making it more reader-friendly.
4. If we ever need to change again the order of some chapters, that's easily doable in AsciiDoc, so none of these changes are so drastic after all, but the immediate benefits are considerable.

In any case, I'd like to read what you think of the new structure.

[AnssiR66]

Hi Tristano! Thanks for the preview and for letting me know. It sounds and looks good. I would suggest that in the first few pages, where the authors/contributors of the library are listed, you also add your own name as the main responsible (or whatever other wording/title is suitable) for the 2.2.0 update - you have been doing / are doing the most work anyways and deserve of course to be credited. Also, I would suggest that some kind of quick start summary would be present early in the manual (or did we discuss something about it being in a separate file? I don't remember exactly), I mean, for people who just wish to start working with the library as quickly as possible. This might be of course what is now an empty chapter there, an overview of the library and its features. Would you like me to write that bit, or do you wish to compose it from your own perspective, and what feels good for you?

[tajmone]

Hi Tristano! Thanks for the preview and for letting me know. It sounds and looks good.

Glad you like it!

I would suggest that in the first few pages, where the authors/contributors of the library are listed, you also add your own name as the main responsible (or whatever other wording/title is suitable) for the 2.2.0 update - you have been doing / are doing the most work anyways and deserve of course to be credited.

The "Acknowledgments" section should be fine, and if the need be also mentioning credits for specific tasks in some places (e.g. AsciiDoc porting). It's customary in the open source world that the original author retains paternity of the work, even if others have taken on maintenance (e.g. Linux is still credited to Linus, even though many other people have worked on its code after its creation), but it's also fair to mention co-editors, especially in text works, so in case of mistakes the blame falls on the latest editor.

Also, I would suggest that some kind of quick start summary would be present early in the manual (or did we discuss something about it being in a separate file? I don't remember exactly), I mean, for people who just wish to start working with the library as quickly as possible. This might be of course what is now an empty chapter there, an overview of the library and its features.

I was thinking of adding an "Introduction" to each Part of the book, briefly describing the specific library feature being discussed in that Part, in order to give the reader a bird-eye view of what's coming in the next chapters. Another approach would be to have a "Conclusions" chapter at the end of each Part, resuming what was learned in that Part, but I think that the former approach allows a reader to be better prepared for his/her first reading of the book, anticipating any doubts. Also, if the need be, a "Conclusions" chapter can also be added at the end of complex Parts.

My idea was to always keep in mind the dual-nature of the book: as a learning manual (to be studied from beginning to end), and a reference guide (to be consulted often while working on real adventures). So, besides the "Intro" (and, eventually, the "Conclusions" outros), the actual Chapters and sections should be easy to consult for quick lookup of topics, besides learning. E.g., the use of admonition blocks (Tips, Warnings, Notes, etc.) simplifies the Ref Guide aspect by allowing users to quickly skim through contents, whereas students will read them while learning the Manual.

Would you like me to write that bit, or do you wish to compose it from your own perspective, and what feels good for you?

Any contents you can write will be a precious contribution, regardless of the format in which you deliver it to me (be it text pasted in an email, a Word document, etc.). So, yes, please do. I'm sure that coming from you, the text will better reflect the StdLib spirit and its history, whereas my ability is more limited to "filling in holes" created by the editorial changes of reorganizing the book structure (i.e. balancing things out, etc.).