This article describes how to create a document, including:
- Adding/Modifying Document Attribute Values
- Modifying Headers/Footers and Title Page
- Defining the Content
- Viewing a Document
- Viewing a Print Preview and Printing
- Releasing the Document
Before creating a new document for the first time, you should be familiar with the SystemWeaver Documents Model.
Creating a New Document from an Existing Template
Typically, a SystemWeaver Architect will create document templates which are used by users when creating new documents. In essence, a template is simply an existing document. Templates provide a type of standardized document structure which includes items that give it structure, such as a title page, title header, title footer, page header, page footer, and that define what content should actually be printed. This way, documents that are produced frequently, for example, requirement specification reports to suppliers, can follow a consistent format regardless of who is generating them. The easiest way to create a new document is to create it using a template. The basic steps for doing this are outlined below and include utilizing the Documents menu tools to work with the newly created document.
To get started, you will need to find the template to be used for creating the new document. How to access your organization's approved templates will depend on which option has been configured by your system's Architect. Typically, templates will be easily available to users via a one-click menu option or users may be instructed to access a list of document templates in the architecture they are working in. Either option is good and helps to ensure consistency of documentation. Another option is to search for the document template as described below in steps 1-3 below.
- On the Items tab, click Open item and then under Type, select General Search.
(Tip: If you frequently open document type items, Document will be listed in your Open item drop-menu and you can select it directly. If you frequently use a template that is never changed, you can add it to your favorites as a quick way to open it in the future.)
- In the Select Type dialog, type Document and then double-click the Document item in the filtered list or select it and click OK. A list of existing document items in the database will display.
- Select the document you wish to use as a template for your new document and double-click it.
- Once you have found the template, expand the Document menu item in the Documents menu group and select Create new document from this template.
The dialog will display a list of every item in the document that includes their Name, Properties and Description. By default, all items are set to be included in the new document.
- To make changes to the defaulted copy option for any item, right-click on the item in the left pane and select the desired option (Create Copy, Include, Ignore). These options are described in Introduction to the Documents Model and Features.Tip: You can hold down the Shift key to multi-select items.
- Once you have set all of the item copy selections and are ready to create the new document, click OK. The New item dialog will display.
- Select Document as an Item type.
- Select the library/access that is valid for your new document under Chose Access.
- Enter the name for the new document in the Name field. Click OK.
The new document is now created containing the content marked as "Create Copy" or "Include" and will open.
Note: At any time you can exit without creating a new document, by pressing Cancel, the window Close button (), or the Esc key.
As part of the copy process, a trace part called Copy of is created and can be viewed at any time for a clone document via the Parts view. This is useful if traceability to the template is of interest:
Adding/Modifying Document Attribute Values
Once the document is created, users often want to modify or add document attribute values. Some attributes may be updated each time a version of a document is created. For example, a document recurrently sent to a supplier may have a different Document Reviewer value each time it is produced or may be approved by different people depending on the function at hand.
- Select the top-level Document item and click Overview. The Attributes section displays at the top. The example document shown below has seven Default Attributes per the template that was copied.
- In the Attributes section, add and/or modify the values as needed for the new document.
- If new attributes need to be added on-the-fly, right-click in the Attributes section and select Add Attributes. (Since the document attributes are often already set, users commonly do not need to add new attributes.) If you want added attributes to be printed, you need to contact the SystemWeaver Architect.
Modifying Headers/Footers and Title Page
If any of the document attributes are configured to be included in the document's headers/footers or title page, any new values that you have entered as described above will automatically display where they are designed to appear in these areas. Aside from these value changes, the headers/footers and title page are not usually modified by end users since they are typically meant to be consistently the same each time a document is generated from a given template. If the headers/footers and/or title page needs to be modified, consult with your system's Architect.
Tip: If you would like to see the template items in the structure tree, you can bring them into view. Right-click on the top-level document item and left-click View. Then check the template items that you want to view and click OK.
Defining the Content
Once you have updated the document attributes, you'll want to review and define the actual content. The content can consist of sections and subsections as well as item types from any of the other models available in SystemWeaver, e.g., Functions, ECUs. Item types from other models are referred to as Section Items in documents and what types of section items you can add to a document is configured by your system's Architect. The functionality of adding, modifying, moving and removing items from a document is the same as with any other structure within SystemWeaver.
Tip: As with any structure in SystemWeaver, you can chose to only view certain item types in your structure tree that are relevant to your work. If you want to ensure that you are viewing all content within a document, right-click on the top-level document item or any section or subsection and left-click View. Select any items that are not currently selected that you would like to view in the tree and click OK.
Modifying and Deleting Items
There may be content that you copied or included (i.e., you are including existing items) from the template that you need to modify or remove from your document.
- To modify an existing item, select it in the tree and open the Overview view.
- Modify the content as needed.
- To remove an item or items from the document, right-click the item(s) in the structure tree and selecting Remove part(s). See Deleting Items and Parts for more information about this option especially in instances where you are wanting to remove (included) items being used in other documents or structures or items that others may want to use.
Note: Typically, if you chose the Include option for content creation in your new document, the original section content will have a Status of Released. If not, be sure that any changes to the section are coordinated between you and the author of the original section.
Adding new items to a document works in the same way as with any other model in SystemWeaver. The meta model allows you to add items as follows:
|Parent Item||Items That Can Be Added|
|Section||Subsection, Section Item (i.e., any item type, such as an ECU or Function requirement)|
|Subsection||Subsection, Section Item (i.e., any item type, such as an ECU)|
- Right-click the document, section, or subsection in the structure tree where you want to add the new content and select New (to create and add a new item) or Add (to add/reuse an existing item in the database). (If needed, you can review topics on how to search for items and how to create items.)
- Modify the added item as needed.
In the below example document called Function Specification Template, a "Model Section" section contains section items "Functional requirements" and "Function specifications".
Tip: If your document needs to include a reference to another document that resides outside of SystemWeaver, you can use a specific item as a "proxy" for the external file. A Document Reference is a SystemWeaver item that includes an external reference link to a file outside of SystemWeaver, expressed as a URL.
Viewing a Document
- Select the top-level document item or any of the document's sections, subsections or section items and click Document in the Documents menu group to open the Document View. The document will display in outline mode in the view. With the top-level document item selected, the view will display with a white background.
- To jump to a particular section in the view, you can select the item in the document structure tree. Its content will appear white while the rest of the content will display a blue background.
Viewing a Print Preview and Printing
When you are ready to print the document, it is best practice to do a Print Preview first to confirm the page count and layout is as you expected.
- Select any item in the document and click Print Preview in the Documents menu group. The Print Preview view will display.
- To print, click the print icon in the Print Preview or on the Items ribbon.
Note: When adding content to an item that will be printed, elements for which you have assigned a fixed width, e.g., images, should be kept/sized to within 18 cm of the work area in the Description editor. This does not apply to text as it auto-grows In the below example, the process image and the table (if the table width has been set to a specific width) will be cut-off in the output:
For elements such as tables, if you set them to auto-size (by selecting the table, choosing Table Properties and setting the width to "auto"), it will behave like the text and will not be truncated in your output.
See Using the Description Editor for more information on formatting Description content.
Releasing the Document
As a final step after generating the document, release the document so that no further changes can be made. You can complete the release step from a couple of different places in SystemWeaver. Because you will be releasing all items within your document structure, the best place to do this is in the Complete Status view.
- Select the top-level document item in your document structure and click Complete Status on the Items ribbon. All items in the structure that are not already CS Released will display in the view (this is the default setting for the view but you can chose to include CS Released items if you like by unchecking the Exclude CS Released checkbox).
- Select all items in the list, right-click and select Release Selected or use the button provided in the view. All of the selected items will receive a status of "Released". If all items in the document structure are released, the top-level document item will automatically receive a status of "CS_Released" which indicates that the complete structure is released and can never be changed. The only way to change it would be to take out a new version. More information about the Complete Status view is available in the Help.
Creating a Document From Scratch
Creating a new document from an existing one, as described above, is the easiest and preferred way to create a new document, but you can also create a document by using the Items > New item menu and selecting Document. If you chose this option, you will then need to add all necessary parts, i.e., template items, Report XML definition, and content via the context menu:
Typically, this would only be done by a SystemWeaver Architect. If you have a need to create an entirely new document and believe that copying an existing one is not a good option, it's recommended that you contact your system's Architect.