Preface
Why this book came into being. Its purpose. Why it was created as a GitBook. You may choose to skip this section or just skim it.
This book came into being because over the years I found myself trying to explain the same ideas again and again and I wished I had organized those ideas in a coherent and organized way. Some of my explanations got lost along the way, too. Having a structure to hold them together should help my ideas and writing by providing pigeon holes, reference points, and sign posts by which to mark the development of vague ideas as they become more tangible and useful.
Prior to starting this book, I tried presenting my ideas on tomelam.blogspot.com, tomelam.com, and Mashweb.Club. None of those venues seemed right for a standalone, easily extensible catalogue of my ideas on Zen and Mashweb. I hope and expect that the present Guide will finally coalesce my words about Zen and Mashweb into one manageable, comprehensible unit.
In addition to drawing together the ideas presented on tomelam.blogspot.com, tomelam.com, and Mashweb.Club, this book is meant to connect together all such diverse sources of digital information as exist to help programmers and web developers use, extend, and further develop the framework. Some of it should be comprehensible to many non programmers and non web developers who have only a general knowledge of computers and the web.
Documenting Zen through through a GitBook might have these potential benefits:
The documentation can be developed chapter by chapter rather than blog post by blog post and can be longer than the typical white paper.
The documentation can be comprehensive and coherent. A table of contents can lay out the pages even before they are written. Pages can be stubs. Stubbed pages can point to external resources to introduce their topics.
Versions of the book can be identified by semantic version names, making the intent of each version apparent. (See also Wikipedia's entry on semantic versioning.)
A two-way synchronization between GitBook and GitHub, editing based upon MarkDown, and periodic pulls from the GitHub repository backing up the book ensure that no work on the book will be lost.
GitBook.com (and the corresponding Git repository) can be used to store all versions of the Guide. Not every Git commit must have a version number, but each version of the book should be stored in a commit and have its own tag that is just a semantic version.
The main "diverse sources of digital information" mentioned above that preceded this Guide are:
the website Mashweb.Club built with Ruby on Rails, with an estimated 1,500 registered users, which is meant to be an attractive and gentle introduction to Mashweb and Zen that many people might enjoy,
a white paper hosted on Mashweb.Club,
a blog site that discusses some of the problems exploiting the web to the fullest,
the website web-call.cc, which is basically just a set of statically served demos, to be maintained for the early release of Zen code for testing and public comment,
the Mashweb team's forum, invisible to all but the Mashweb team members,
which documents many of the important development decisions about Zen and web-call.cc, and
the web-call.cc wiki, which can be edited by Mashweb team members.
The white paper (#2), the blog site (#3), and the personal website (#4) will be replaced by this Guide and be deprecated. Eventually Alpha Zen and this Guide will be released together and hosted on a completely revamped Mashweb.Club (#1).
Tom Elam, April 2, 2021, updated April 23, 2021
Last updated