- Created by Robert Reiner, last modified on 21. Oct 2019
projectdoc Toolbox
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.
- ID
resource- Suite
- Documentation Type
- Categories
- Tags
Description
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.
Properties
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.
Publisher
The publisher or organization responsible for publishing the resource.
Organizations list resources they have published.
Since version 6.1.1.
Type
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.
Media Type
Document the media type to categorize the resource by its format.
Valid types are defined by the team as media types.
Since 11.1.0
Available since version 11.1.0 of the Core Doctypes.
Version
The version of the document.
For a book this is the edition. Other documents may provide a numbered version.
Publication Date
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.
License
If there is a license that explains the defined usage of the resource, reference it here.
Source
Specify where the original resource is located. Add the URL to the online resource here.
Since 11.1.0
Since version 11.1.0 of the Core Doctypes this link points to the origin source.
See the Download property for referencing to local copies.
Location
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).
Since 11.1.0
Available since version 11.1.0 of the Core Doctypes.
Rating
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.
Image URL
The image or the URL to an image. The URL 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.
Sections
Description
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.
Summary
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.
Excerpt
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.
Quotes
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.
Subordinate Documents
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.
Notes
These are internal notes that are usually not exported and only visible to team members with write access.
But this is not a safe place to store sensible information. It is just a convenience for the reader to not be bothered with notes stored here for the authors for later use. The security level is about suppressing the representation by a CSS style. Therefore consider this as a convenience for the reader, not as a security tool.
The text of notes sections is also indexed.
References
For a document the references section contains pointers to resources that prove the statements of the document.
Often these proofs are not easily distinguishable from further information. In this case you may want to skip the reference section in favour for the resource list.
For further information please refer to References and Resources.
Resources
The resources section provides references to further information to the topic of the document.
This may be information on the internet provided by the resource or information in the team's information systems. Anything the reader of the resource might want to know, may be listed here.
For further information please refer to References and Resources.
Details
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:
| Name | Short Description |
|---|---|
| Cite Macro | Renders a cite to a resource document. |
| External Quote Macro | Renders a quote to an external resource with author and source. |
| Quote Macro | 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.
Naming Resources
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.
Related Doctypes
Person
The resource document may reference authors stored as person documents. This allows to automatically collect resources authored by the person in the person document.
Resource Type
The resource type document type lists all resources. The resource type document instances also collect the resource document for quick access.
Structuring
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.
Role
Roles are used to determine the audience for a resource. This may also help readers to set their expectation on the contents of the resource.Resources
- 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.
