Resources are books, webpages, videocasts relevant for the project. Add important information to your project about resources that lie outside the control of your team.
A resource document stores information about a resource of information that is relevant for your project.
A resource may be a book about agile testing. The resource document provides information about that book:
- Who wrote it?
- When had it been published?
- Is it available online?
Besides this metadata a resource document also allows to add descriptions and summaries about the resource to allow your team members to understand the relevant parts for your project quickly. It may even be connected to Excerpt document that provide in-depth information on topics of the resource.
The document type resource provides the following properties:
Please note that only information about specific properties is provided here. Common document property used by all document types are documented by Document Properties.
Lists the authors of the resource.
Persons list resources in their bibliography.
The publisher or organization responsible for publishing the resource.
Organizations list resources they have published.
Since version 6.1.1.
The type of the document.This allows the reader to judge how the information will be presented.
Valid types are defined by the team as resource types.
Document the media type to categorize the resource by its format.
Valid types are defined by the team as media types.
Available since version 11.1.0 of the Core Doctypes.
The version of the document.
For a book this is the edition. Other documents may provide a numbered version.
The date at which the resource has been published. May be the year only or more precise.
This may help readers to set several resources into context.
If there is a license that explains the defined usage of the resource, reference it here.
Specify where the original resource is located. Add the URL to the online resource here.
Since version 11.1.0 of the Core Doctypes this link points to the originl source.
See the Download property for referencing to local copies.
Provide a links to download copies of the resource locally.
Consider to use the format of the file as label for the link (e.g. PDF or XLS).
Available since version 11.1.0 of the Core Doctypes.
Rate the relevance and accuracy of the information provided in the resource. This should help team members to judge in advance, what can be expected.
The URL to an image. May be a plain URL or a link that points to an image.
Typically the URL is used to fetch the image and render it using the Display Document Property As Image Macro.
A description of the content. This is the longer version of the short description that should help readers to decide, whether or not reading the resource will help them for their demand.
Often the short description is enough. So leave this blank.
The summary describes the content of the book in a few paragraphs. Other than the description, which describes the topic of the book, a summary holds is essence.
There is often no time to write effective summaries on a project. In this case leave this empty and go with a short description and the most helpful excerpts.
This section contains the excerpts that express the topics of the resource in more depth. For a book there might be one excerpt per chapter, if this information is relevant for the project.
If you can keep it short, replace the list with information added as subsections.
A collection of quotes taken from the resource that are relevant for the project to be referenced from elsewhere in your documentation.
While most quotes may be located directly in any doctype, using the Quote Macro, the important once may be added as child pages to the resource document. Note that these quotes will show up on the index page of the Quote Doctype.
For some resources there is a natural partitioning of a document. There might be a business rule that is split in several subordinate document. You may want to track different versions of a resource where the latest is referenced by the main resource document.
If you do not need to make this relationship visible, skip this section.
Quotes and Cites
Resources make it easy for authors to quote information provided by them. This might be useful in other documents.
Here are the macros to support authors with quoting and citing:
Renders a cite to a resource document.
Renders a quote to an external resource with author and source.
Renders a quote from a resource with author and source.
Note that you need not specify the resource document for including the source's metadata into the quote on a resource document or a excerpt or quote document that is a subpage of a resource document. This resource document is automatically the default if the Wiki Page Property is left blank.
Tips on Using Resource Documents
For projects the resource documents are usually quite short. It is useful, especially for new team members, to get in the context on which resources the team is running this project. So resources can easily be compiled into reading lists for different roles of the team.
Resources, especially book names, may not be unique. Especially if the book defines concepts like Martin Fowlers Refactoring or Jez Humble and David Farley's Continuous Delivery. It might proof useful to set the name property of the resource document to the title of the book and use the last name of the first author and publishing year as the artificial title of the document. This reduces the collision with titles of other wiki pages in the same space. If the author has published several resources in the same year, add a counter to make the title unique.
Following this suggested rule, Martin Fowler's Refactoring book may be named Refactoring and titled Fowler1999.
The resource document may reference authors stored as person documents. This allows to automatically collect resources authored by the person in the person document.
The resource type document type lists all resources. The resource type document instances also collect the resource document for quick access.
The tag and category document types provides means to put structure on resources to help readers find the demanded information more quickly. While this is true for nearly any document type, it is especially true for the resource document type. Even more so, if the resource library gets quite large and is a knowledge base for several projects.
RoleRoles are used to determine the audience for a resource. This may also help readers to set their expectation on the contents of the resource.
- Collecting Information - Get users started with collecting external information that is relevant for their project. Each piece of information is referenced by a resource document. Excerpts and quotes are used to catch detailed information and make it referenceable.
- External Resources - List of references to external information. This allows to link to an external resource that is not in control of the team and add information that is relevant to the project.