New Author Guide
This guide is designed to help you, the new author, get started creating and publishing content in the repository. Below you will find a basic outline of the process as well as a few best practices to help you get the most out of your work. You will also find links to additional resources should you need more detailed explanations.
- The Connexions Model
- Creating Modules
- Creating a Collection
- Workgroups and Collaboration
- Authoring Best Practices
- Additional Resources
The Connexions Model
Before getting started creating content, it is helpful to understand a little bit about how Connexions works. The figure below shows the basic process in action:
As the author, you already contain the raw ingredients - the knowledge - that make this system work. Using the authoring tools that we provide for you, your job is to package that material as individual learning objects called modules. These modules are then collected in the content repository where they can be used by themselves or combined to form collections - textbooks, online courses, lab manuals, or any other structure that you can think of.
The great part about this system is that everybody shares the content repository. For example, suppose that I have created 15 modules on the topic of statistics for a math course I am teaching, and have published my content. I can combine these modules into a collection - in this case a textbook. Another instructor can take those same modules, mix in a few of her own, and create an online course. Another author may choose to take one of my modules for use in a research methods lab manual. By adding my content to the repository, I've enabled everybody to customize that material to fit their own needs, and have encouraged others to add content that I may be able to use myself. In other words, sharing is good, and we give you the tools to make that sharing easy.
Once modules and collections have been published, those learning objects can be added to one or more lenses. Designed as a post-publication review option for users wishing to identify or endorse high-quality content, a lens allows readers coming to the site to "focus" in on a set of content defined by an individual or organization. Each lens creator has complete control over what content is added to that lens, allowing them to use (and make public) their own criteria for inclusion, and can add comments and tags to further describe the value or relevance of that work within the lens context. Lenses can either be public or private, allowing you to manage your own favorite content or share your selections with other users. A complete list of publicly viewable lenses can be found by accessing the Lenses tab.
When authoring, your goal isn't to write one single, all-encompassing document that covers a topic from start to finish. Instead, the goal is to create several small, self-contained "chunks" of learning called modules.
A module is designed to be a relatively short, standalone learning resource - a chapter, a section within a chapter, a journal article, or a single lab experiment, to name a few examples. A well-written module can be taken out of context and used by itself, or can be combined with related modules to form a larger work, or collection, such as a textbook or online course.
There are no length requirements specified for modules, but for practical reasons these should generally be no longer than a few pages of printed text. There are two reasons for this guideline:
- Modules longer than a few pages can often be broken down into smaller, standalone chunks of learning; generally speaking, the smaller the pieces, the easier they are to reuse later on by you or other authors.
- As most readers will be accessing your content on the website, you will want to keep the page length relatively short for readability purposes; each module corresponds to a single webpage, so longer modules will result in more page scrolling.
The CNXML Language
All modules are created using the Connexions Markup Language, or CNXML. CNXML is a specialized version of XML (eXtensible Markup Language), a method for describing information in a document so that it can be easily interpreted by computers. While it may take a little time to get used to, the CNXML language allows you to create a single document that can be used for web-based, PDF, or print delivery without having to worry about formatting or maintaining multiple files at once.
More on Modules
For more information on working with modules, see the Creating a Module and Editing a Module guides which provide a basic walkthrough of the content creation process, including information on importing content from existing documents.
Creating a Collection
Once you have broken your content down into modules, the next step for most authors will be to put it all back together again as a collection. If you think of modules as individual building blocks, then collections are the things you can build out of those blocks - in this case textbooks, courses, lab manuals, journal issues, and so on.
As a collection author, you are free to use any combination of published modules from the content repository, including content created by others. The collection composer allows you to arrange those modules in any order, create "chapters" or other hierarchical structures, and rename modules in order to give you complete control over the organization of the content. Once published, readers can access your collection as a free online ebook (available through the website), download a free PDF copy of your collection for printing or sharing, or even order a low-cost printed version of the text through our print-on-demand partner.
For more information on creating and editing collections, please see the Create a Collection guide.
Workgroups and Collaboration
Before publishing a module or collection, you will first need a place to create and edit your content. This can be done in workgroups accessible through the MyCNX tab. You'll also need to understand the the different states in which a draft can exist, as well as how to assign attribution roles to yourself and your collaborators.
There are two types of workgroups: the Personal Workspace and Shared Workgroups. These workgroups allow you to develop draft content prior to publishing, giving you an opportunity to explore and experiment with your content before sharing it with the world.
Every member account has a private work area called “Personal Workspace”. As an author, you are the only person who can access this work area, making it an ideal place to develop personal projects or create a "sandbox" for experimenting with CNXML. If you decide to share this work with others, you can simply move your current draft into a shared workgroup (where only other workgroup members can view it) or publish it to the repository (where it can be viewed by anybody).
You can also choose to create one or more shared workgroups for collaborating with other authors. Unlike your personal workspace, shared workgroups allow you to invite others to view and edit your content, making it an ideal place to work on group projects or get feedback on draft content. Note that in a shared workgroup, each invited member has the same rights to create, edit, and discard a draft - there is no hierarchy within a workgroup.
Once you've created modules and/or collections within a workgroup, you'll see a content listing similar to the following:
You'll notice that the far-right column describes the content's state. This can have four possible values:
- Created: Content in the Created state has not yet been published and exists only in draft form. No version of this content can be viewed by anyone outside this workgroup until it is published, and discarding this draft before publishing will permanently delete it.
- Published: Content in the Published state has been published to the repository and made available for everyone to see; there is currently no working draft checked out to this workgroup. To make changes, you will need to check out a new working draft.
- Checked Out: When you check out a copy of a published module, an exact copy of the content is added to the workgroup and placed in the Checked Out state. While no changes have been made, a working draft is available for editing.
- Modified: When you make changes to a draft copy of a previously published module, it is placed in the Modified state to indicate that the current draft is different from the published version. These changes will not be available to all users until the current version is published (which will put the content back into the Published state).
We use roles to assign permissions and attribution to a module or collection. There are three required roles that must be assigned for every piece of content before it can be published:
- Author: An author is someone who gets credit for creating a work. This is not necessarily the person who entered the content, but rather the person who should get credit for the ideas behind the content. Multiple authors can be listed for the same content in a specific order (i.e. first author, second author, etc.).
- Copyright Holder: The copyright holder is the person who actually owns the rights to the work, and is the person responsible for licensing the work under the terms of the Creative Commons Attribution license. As with authors, it is possible to list more than one copyright holder. Note that while authors are often the copyright holders on original works, this is not always the case; some examples include organizations that own copyrights to works created by their employees, or authors who have sold or transferred their copyrights to another party.
- Maintainer: While the author and copyright holder get credit for creating and owning the work, respectively, the maintainer is the person responsible for editing and publishing the content. Only users listed as maintainers have permission to publish updates to a module or collection. Many authors will choose to act as a maintainer for their own materials, but some may choose to hand that responsibility off to another individual or group, such as a graduate student or assistant. As with the other roles, it is possible to add multiple maintainers.
In addition to the three required roles listed above, there are two optional roles for content:
- Editor: A user listed as an editor receives credit for editorial contributions towards that content. Editing duties may include checking the material for accuracy, grammar, spelling, organization, and so on. Unlike authors, editors do not take credit for the ideas behind the content, but rather for its organization and presentation. Editors do not have rights to publish materials, so editors who are also responsible for keeping modules or collections up-to-date must be assigned the maintainer role in order to publish new versions of the content. Editors are listed under the "More about this content" link that appears at the end of the module.
- Translator: A translator has taken existing content and translated it from one language into another. Translators are listed next to the authors' names in the content headers. As with editors, translators do not have permission to publish or update modules, so translators with publication responsibilities should also be assigned as maintainers for the content.
We use roles to display and maintain proper attribution for modules and collections, as well as for derived copies of existing content. When you change roles for a module or collection, a role request is sent to any user who was added or removed from a module's collaboration list.
These changes do not take effect until all parties with role changes accept the role requests and the content is (re)published. This process ensures that all users have an opportunity to approve of any attribution changes with which they're involved. Modules and collections cannot be published while role requests are pending.
Authoring Best Practices
The following tips and best practices are provided to help you avoid some common mistakes and pitfalls that new authors run into. These are not rules, but rather suggestions and recommendations that will help you develop your content in a way that will make it more useful ad reusable for you and other authors.
Modules should be able to stand alone
Some readers will access your content much like an ebook, starting at the beginning of a collection and reading each separate module in turn. However, you'll probably find that the majority of your readers will find your modules as the result of an internet search engine, meaning that they'll start somewhere in the middle and not necessarily within the context you were expecting. Similarly, other authors may wish to use your content in a context other than the one you anticipated. When writing your modules, always try to remember that they may be reading the content out of context, and make adjustments as necessary.
Use links when referencing materials
Try to avoid referring to content in another module with phrases like “as seen in the following section”, “the previous section”, or “later in the course”. Instead, refer to the title or a description of the material and include a link to the material you want the reader to see. This can be a link to another module, a part of a module, or a Web page outside of this website. Doing this will ensure that you can point your readers in the right direction even if they aren't looking at the entire collection.
Add featured links in your module
You are allowed to include a set of featured links to related resources. These links only appear in the online version of the content (the do not show up in the PDF or printed book), and are very useful for directing users to external references, prerequisite materials, or downloadable attachments. For each link you can provide a score (from 1-3) to indicate how important or relevant that link is to the current content. You can also assign that link to one of the following categories:
- Example: Helpful for providing practical examples of an abstract concept.
- Prerequisite: Useful when the current topic requires specific background knowledge or skills.
- Supplemental: Indicates that materials are related to but not included in the module, such as a class handout or reference table.
Word your titles carefully
The title of your module is the first, and sometimes only, part of your module that your reader sees. In a few words, the title must catch the reader’s interest and inform him or her about the content of your module.
- Be descriptive and be concise
- Write a title that tells the reader what is in the module. A short title like Introduction, History, or Chapter 1 does not have much meaning to the reader when it appears in a list of search engine results. The title Overview of Fast Fourier Transform Algorithms (FFTs) gives the reader more information than does the brief title Overview.
- Avoid numbering
- Do not limit your title to a chapter or section number, and do not include such numbers in your title. You or another author may reuse the module in a different course where the number would not be appropriate. Also consider that there could easily be several hundred "Chapter 1" modules in the repository; you need to be able to tell one from the other, and the best way to do that is to describe the content - and not the usage - of the module.
- Do not rank or order
- Do not express an order of appearance in your title, such as Approaches to Playing the Piano: Part 2. Readers who find this module outside of the context of your course will be wondering what are the other methods of playing piano. A better title might be The Lipatti Approach to Playing the Piano.
It is important to always include a useful, descriptive, and well-written summary when creating a module or collection. These summaries do not necessarily have to be long - most need only be a sentence or two - but should tell the user something about the content about to be presented. Summaries are used in search engine results, as abstracts when viewing individual module PDFs, and are always displayed at the top of the page when viewing content online, so you want to make sure that the summary is well-written (use complete sentences!), accurate, and descriptive.
Summaries may contain a limited subset of CNXML markup. In most cases, summaries act as a CNXML paragraph (<para>) element and can contain any of the following:
- Plain text
- MathML content
Instead of treating the summary as a <para> element, you can also choose to use the following structural elements to create more complex summaries:
If you would like to see more information and step-by-step instructions for authoring, please see the Connexions Tutorial and Reference course. You may also find it helpful to review the pages linked from this document, as well as those listed on the Authoring Content menu.