Make It Fun
The enclosed sample comes from Ultima Ascension, the ninth and final chapter in the Ultima series created by Origin Systems of Austin, Texas. Since the first Ultima game appeared in 1981, the Ultima universe has since acquired a life of its own, inspiring reams of fan sites, additional fiction, and even an online version that is very popular.
User documentation doesn't have to be dull. If your project is meant to be fun, a bit of flavor and flourish in the writing adds value for the customer. The most important objective is to communicate how the software works, of course. But if you can manage that and lend a smile or a dream to your audience, you have done better than most.
From the beginning of the writing project, it was clear that the two manuals, a Spellbook and a Journal, were intended to embellish the Ultima chapter on the CD-ROM. This sample comes from the beginning of the Spellbook.
Many summers ago, from the door of my cottage, I watched a figure climb through the stand of pines towards my retreat at the high end of the valley. He came alone and unarmed. Not wanting the disturbance, I conjured a Gust to drive him away, but he banished it without breaking stride. Here, I knew, was a man of great magic.
Yet he was no man. The figure did not trouble to open the gate and instead passed directly through it into the yard. In this age of clouded magic, for this spirit to appear with such clarity at my doorstep, I knew, he must have been in life a man of broad powers. For him to arrive from a distance showed a respect that I could not ignore.
The spirit did not bother then with greetings. I, he said, would scribe a screed on the practical uses of magic for warriors. Magic for warriors? What, I queried, did I have to say to such clumsy trolls? For what reason would I speak to them?
My thoughts were consumed with the clouding of the ether, the breath of the magic of Virtue. Since the days of my apprenticeship, the ether had been sullied by forces unknown and for reasons unexplained. Without clarity to the ether, the magical arts of the Virtuous had faded, and in their place had risen the magic of a dark form of ether. To the few who upheld the traditions of Virtuous magic, the addition to our ranks of such a troll, who lacked neither the inclination nor the discipline to further our research into the problem, verged on insult. I dismissed Hawkwind from my cottage with a request to never disturb me again.
Ah, Hawkwind was a pest! Each year, his spirit interrupted me in my sequestered glen. Each year, I threw my newest, most powerful scroll-magic at his projection. Each year, he threw it into the dung heap. While my two apprentices, Arduin and Grimwar, giggled at my failings, I grew flattered at the attention. His visits spurred my studies, which had flagged in the face of the problems of the ether.
This Practicum became a yearly discussion. I, let it be said, did no work on such a thing, as completion of it might end his visits. Over many years and many visits, the project gathered shape in our talks. After each talk, I wrote notes, filed them in a drawer, and returned to my humble trade of scribing astronomical texts.
On a sleeting winter’s night two months ago, I lay in the necromantic sleep when a pounding nearly shattered the door to my cottage. In suspicion of a Grimwar prank, I threw a magic dismissal at it and rolled over. Yet it did not go away. At the door stood a messenger known to me from a village several days east. He gave a talisman from his neck and a package to me and vanished into the weather.
The package contained a note, a scroll, and some herbs to aid the mind's eye. Hawkwind had given me a mighty spell with which to view the maps of the future. The time had come, Hawkwind, indicated. Use the spell to see what may be. You will bring the Practicum to the Festival of the Vernal Equinox, two months hence.
Before Arduin and Grimwar arose, I placed the talisman around my neck and cast Hawkwind's magic. My mind's eye opened on a smoldering plain of great stillness, a place where no tree grew, no rock rested, and no water flowed. Though clouds of other futures floated like ghosts, I did not plunge into them, for there was but little to their ephemeral shape. In the distance, rose cries of pain or perhaps the roars of victory. Towards them, I hurtled and across the plain did not feel any locus for the Virtuous ether that feeds my being. I flew over the ruins of a city of such greatness that it could be but Britain. Harried figures scattered below, as if cringing before my apparition. Onward, I flew. The voices grew louder yet did not divide into people or creatures in the thickening mist of these other futures. Onward, I flew until I could not see, until the roar of voices changes to laughter, to a derision without a face. All of the futures mocked me and my hollowed core of Virtue. In the swirling doubt, my hold over the spell-magic began to slip, and downward I tumbled through the plain into a blackness that was scattered by the candlelight of my study.
I hastily gathered my notes and did not leave them for a fortnight. As I scrambled through my library to assemble the pieces into finished form, chores about the cottage were forgotten. The animals were allowed to roam free. Arduin and Grimwar got into much mischief, yet I did not have time to address them.
It is now the eve of the Festival of Vernal Equinox. A conjure finishes the scribing of this letter. The process has humbled me greatly. In attempting to teach, I have learned how little I know, truly, of the ways of Virtue. How can I, a mortal, know? I do not know. I do not know. Those four words, I have learned, mark the commencement of the pathway to wisdom, a limitless road that now stretches before me.
It occurs to me that I do not know for whom this Practicum is intended. You are a warrior, a quester. Through your practical means, you must close this crossroads on time's highway. That is all I know. To you, whoever you may be, I offer this limited text and, of greater importance, courage and patience in the pursuit of your chosen truth. May your journey towards it be straighter and truer than I to mine.
• The Mage Genser, Eve of Vernal Equinox
A Practical Creed on Magic
Some of the brightest minds expend their life-energies probing the mysteries of magic. A rare few can claim mastery. For most, the study of magic is a detour on the path of life into a bramble of frustration or, alas, into a madness from which they do not escape. If you follow this text to the word, you will suffer none of those fates. You will not suffer the frustration, for the lessons herein are simple and direct. You will not suffer the madness, for you will know not to ask the most dangerous question of all: why?
You will learn the ingredients and requirements of spellcasting and some limited understanding of elemental magic. At the conclusion, you will be offered a summary of sundry magic to be found in Britannia. You will know these spells and the nature of potions, scrolls, and the magic of the Moongates. You will know these spells, and you will feel the flow of flawed ether in the world. Yet of these things, you shall not question. Your fate is to never know the Why.
In the loosest form, magic spells are a harvesting and concentration of the energies of the ether through the person of the mage. Like a focal lens, he attracts these energies to himself and thence expends them outward through the triumvirate of mental exercise, invocation, and placement of objects. These three elements are broken into a complex swirl of untenable mathematics, alchemy, and structured language, the mastery of which consumes the better years of a mage’s life.
During your travels, you may acquire magic through scroll or spoken word. You can cast the spell from a scroll immediately at no cost. However, the energy of binding within the scroll is released, and the spell is thence lost. Should you desire to retain the spell forever, you must inscribe it into your spellbook with the Ritual of Binding, which cannot be performed for the spell until its Circle of Magic is opened to you.
A magician must have a spellbook to assist in the preparation of each spell. Do not lose your spellbook. Neither lose it nor share it with another, for once you invoke the Ritual of Binding, the book is bound to your life force.
In clearer ages, a mage used the Ritual of Binding to inscribe spells into his spellbook as he acquired them. An inscribed spell was known to the mage forever. Thusly, he did build his repertoire as a spellcaster.
Through knack and training, a spellcaster acquired mana, the creative energy of the ether from which the Eight Circles of Magic draw. Yet, these Circles have closed to all mages of Virtue. To bind a spell of Virtue, the Circle to which it belongs must be opened. To your spellbook, you can bind only the limited spells of Linear Magic.
To cast a spell from a spellbook costs mana. Expended mana can be recovered by rest, ritual, or potion. A mage can improve his mana in the performance of righteous deeds. There exists a black form of mana which, though freely flowing, you shall not use. You are a mage of the righteous. Endeavor to do the Virtuous Deed, and your powers of magic will grow.
The magic of this tome has been divided into four parts. Terse discourses on mana, your link to ether, and on Reagents, the binders of the more powerful forms, comprise the fore part of the book. A listing of the spoken words of magic begins your focused study of them. Thence come the spells. Although the light and safe casts of linear magic are of little risk and, thus, of small reward, they can be of some assistance during your travels.
The eight Circles of Magic follow in order of increasing power and difficulty of mastery. The Circles, alas, are yet closed to magical inquiry. Where the ether is not controlled, magic cannot be bound inside the Circles. That Hawkwind has asked for the inclusion of the Circles births hope in my heart that you may be the one who brings clarity to the ether and fills the mana of all mages. Should it be so, yours would be the name scribed across all of magic history hence.
In this clouded age, mastery of ether, the breath of magic, is but a dream. To its former masters, the ether is a tangle of impurity. To new initiates, it defies understanding and is readily dismissed. Ours is a faith that gathers few new acolytes. As our ranks thin, so grow the legion of mages who draw upon the dark form of ether.
For the elders among the fraternity of Virtuous mages, the memory of clear, pure ether draws forth pangs of a youthful innocence that may never be regained. Before the Columns, ether was all about us. It was in the beating heart of a stag, in the tremulous changes in the leaves of autumn, and in the tide of the sea. It was that which connects all living things. Now, its purity has been defiled, and the spirits of life stumble after each other in the darkness. All life suffers in the misery of this isolation.
Inside each mage is a great and empty space that, in richer times, was filled with mana and expended in the casting of magic. Like the breath, ether was gathered to the mage and expelled through invocation and thence gathered again. In this bleak time, one's mana continues to seek the ether yet finds no satisfaction in it. For, to grasp at impure ether is to gather water between the hands. Though it can be held for a time, it cannot be shaped to one's will. Soon, the murky ether slips between the soul's fingers and returns to the soil.
Should your quests begin to open the ethereal void, you too will sense the growth of mana in your spirit. For in so opening the void to others, you have done the good deed, and the mana that governs the Eight Circles of Magic herein is drawn to the fires of Virtue. Do the good deed, it is decreed in the fabric of your spirit, and you will gain a new understanding of the connections that flow between all things in the world. Thusly will your mana grow.
In the Circles of Magic, the casting of a spell drains the mana of the caster. Some spells continue to draw upon this well until it has been depleted or the magic is dispelled. They with the greatest mana shall find these duration spells of grandest use.
To create a potion or to bind a spell to your book requires the presence of morsels both rare and common through which energy can be channeled and multiplied. Most spells require particular reagents whose properties bind the unique magic of the spell into the spellbook. Once bound, the magic of each spell is retained in the book while the mage imbues it with his life force. When a mage dies, so too fades the magic of his book.
During travel throughout Britannia, a disciplined mage must always search for reagents. Among common magic shops, you can find the base reagents. Rarer types are hoarded and require patience to find. A forgotten shop or forlorn peak may reveal a secret supply.
Some mages scoff at the Ritual of Binding. What good, they say, comes from knowledge of a ritual without use? Why learn to bind magic when it cannot be thence harvested? In this world of clouded ether and deep confusion, these naysayers gather others to their opinion. Yet, I have seen one future, and to ward us from this troubled end, each mage must attempt to build a spellbook. Though you cannot cast the spells of Virtue from your book into the world, you must prepare for the day when such is possible and the darkened world cries for it.
The use of reagents in potion-making is described elsewhere.
For spells of Projection
Born of an oyster bathed in water magic, a black pearl channels energy of projection in manners both forceful and absurd. Like the water from which it was born, black pearl can bind spells of thrown magic. In equal measure, it can make quite a mess. As a young apprentice, I sought to bind a Fireball spell and, in poorly performing the Ritual of Binding, engulfed my spellbook in flame. A few mages have found steady sources of Black Pearl, yet they are loathe to reveal them.
For spells of Movement
The energy of blood roiled in battle imbues a common type of moss with a magical potential that is suitable for spells of movement. In binding with this reagent, the mage draws from it the carriage power of the blood contained therein. Sadly, the moss seems to favor the blood of virgins, and reports of abuses have spread from the hinterlands.
For spells of Protection
For eons, common garlic has warded off creatures of undead enchantment, though some have developed resistances over time. In magical application, garlic has powers of protection that invest themselves in the binding of these spells. Yet the usage of garlic can make one weep like a child. Against this power, there is scant protection.
For spells of Curing
In ancient eras, ginseng was crushed into a fine powder and added to the ale of warriors on the eve of battle. Many awoke dead in the following morning, and much good ginseng was wasted. While you may choose to use ginseng as a primitive invigorator, such a preparation releases a sliver of its restorative powers. In magical application, ginseng binds curative spells and in the glimmer after the binding surrounds your person in a pleasant scent.
For spells of Power
Mandrake root was known to mages of yore as the Root of Life for its aptitude in binding spells of power. Once thriving on silted riverbanks, this root in the shape of a human form has since become quite scarce. When found, keep it on your person, as the lowliest thief knows its value on the black market.
For spells of Illusion & Poison
A deadly plant if eaten, nightshade can bind illusions or, if used by different method, spells of poison. Nightshade is so named for its nocturnal growing habits. Of such rarity is this reagent that few know to begin a search after the day has passed. For they who do, such a search is often futile, as nightshade is visible only by means of spell-magic. Yet, it can be so found throughout the lands.
For spells of Binding & Holding
Little in the natural world has the tensile strength of a spider’s webbing. An ounce of this predator’s trap, prepared by a mage, can bind spells of holding and binding. Use spider's silk that has been prepared under proper standards. Though you may find natural samples in your travels, a magic shop knows your intent better than the spider that spun it.
For spells of Amplification
Sulfurous ash holds the energy of friction from the volcanic eruption that begot it. For magical uses, ash is mixed with other reagents to amplify the energy effects of a spell. So powerful is this reagent that experienced mages can hold a spellbook and know by touch its ashen contents.
The Dicta of Magic
Dormant magic does not have good ears. The power of the ether must be drawn forth with a bard’s command of voice and inflection. It is mere child’s play to memorize these words. Young Arduin, my apprentice, learned the names of the Dicta before the completion of his chores on his first day in my care. But he has yet to master them, for to invest them with the proper charge requires a full breath, a resonant tone and a mind clear of distractions. A bright boy, Arduin has discovered that a projection of these tones through his mind’s eye as a flame to ignite the spell produces a finer result. He and I practice the sounds of magic each morning, while Grimwar is, alas, off teasing the pigs.
Thus begins your study of spell magic. A good student binds into his spellbook the preparation of each spell presented to him. A bold one commits it to memory. And an impatient one throws the casting of the mind into the world around him. They who have leapt into casting can attest to results both humorous and horrific. While your path leads through the warring arts, you must respect the ways of magic to master these practical spells. Practice the safe casts of linear magic each day so that you may be prepared, should the Circles of Magic open once again.
Fate, alas, has decreed that it is so. For many years, the Eight Circles of Magic have been denied. Ether, the life of magic itself, defies reason and control. To some, the mages of old who could control the ether have brought shame to our failure. Under this dark shadow, we do not gather new numbers. We age, we die. I trust that your fate is tied in some manner to ours. Should chance present itself to you, unfetter the ether before we who can harness it leave this plane.
Until clarity returns to the ether, you can use but the spells of Linear Magic. Let these simple casts aid in small ways your travels. Let them whisper of the greater wonder hidden to we mages of Virtue.
To cast a spell requires knowledge, invocation, gesture, and more than a thimble of intelligence.
E – Stone
Invocation – In Bet Ylem
Suitable for stupid, awed creatures, the Stone spell finds favor with apprentices of equally small impression. Grimwar has adapted this spell to juggle baubles to the delight of peasant girls and to hurl these stones when their swains arrive. In more practical form, Stone draws a rock from the earth and flings it at a target.
A – Gust
Invocation – In Hur
Powered by a Titan’s breath, Gust can force a weighty object from its station. A burst of air carries forth from the Mage’s person, and all inanimate matter is subject to its will. In peaceful application, it can jar loose items out of reach.
F – Ignite
Invocation – In Flam
An ancient spell drawn from a pool of magic long since faded, Ignite is still a useful means of lighting suitable items. Many a winter night at the cottage has been cheered by the Ignite spell. Once, overly so. In his first attempt at this spell, Arduin destroyed the corn crib which to rebuild took a fortnight from his studies.
W – Douse
Invocation – An Flam
The foil of the Ignite spell, Douse extinguishes flame in a given location. When Arduin ignited the corn crib, he discovered that Douse has limited application and is not suitable for larger fires. Since then, Arduin has mastered the casting and finds frequent use in dousing the pranks of Grimwar who seems to prefer the destructiveness of Ignite.