Assist Editing Guide

General

• Before editing, you should log in - the Assist system will not allow you to edit the documents unless you have, so that all changes can be tracked to the user that made them.
• You should change your user page within Assist to list your contact details (email and phone number) so that other users can easily contact you.
• You can add to a user's talk page by clicking on their name and clicking the Discussion tab.

Document Editing

• When creating a new document, you should ensure that the Category tags are added relevant to that document type and client. This allows for easy searching of documents.
• Each change you make, however small, is included in the document's history. To ensure that these comments are not included, you should mark the change as minor when saving your changes. However, this should not be marked as minor if the edit fundamentally changes the document.
• Comments should be added whenever saving edits. If you have edited a section directly, rather than the whole document, a comment will already be entered for you. You can leave this there, replace with a new comment or add your comment after this one.
• When a document is going to be changed to a new version, you should change the version and date within the document, and add the version number to the start of the comment. For example:
  • v0.2 - draft issue for review
  • v1.0 - issued after review
• A document should be checked that it exports to PDF correctly - in most cases, documents will export with no issues. However, it has been known that a document does not correctly format into PDF. If this is the case, the document should be referred to the Assist maintainer for checking. Documents can be exported to PDF from the toolbar.

Standards

To maintain a fairly standard set of documentation, use the following guidelines:

• Buttons should be in Bold.
• Tabs and menu options should be in italics.
• Leave two lines between sections.
• Use templates - see section below.
• Reuse documentation where possible - if there is already a page describing how to use something, include that page like so: {{:Planning}}

Templates

Where possible, the templates created for you should be used when creating and within the document.

• Document templates have been produced for the following document types:
  • Requirements
  • Estimates
  • Functional Specifications
  • and many more.
• These can be accessed through this page.
• The following templates have also been created for editing purposes - use them with double curly brackets like so: {{Note}}:
  • Note - This provides a note graphic Note: like so
  • Warning - This provides a warning graphic

    Warning:

    like so

  • Xref - this provides a cross-reference in a standard format. Use it like so: {{Xref|Type=Image|Num=1|Text=An image of something}}
  • Incomplete - this adds a warning that the document is incomplete, and adds the document to an Incomplete category, so it can be easily found and completed. Use it like so: {{Incomplete}}
• Generic Glossaries have been provided for the CALIDUS products. These can be added to if required by clicking on the glossary template in the editing screen.
• Test Plan templates are available to construct test plan cycles - see the Functional Specification template for details on how these work.
• A Comment template has been added to identify comments added to a reviewed document easily

like so

—User:Anw, 31/1/2012 16:33:36

Issuing Documents to a Client

• Documents should be issued in PDF form.
• The document title should follow the standard document template, with a version number, so:
  • EST 123456 CUSTREF Title v1.0.pdf
• If you use the standard document template with the Doc_Title title page and you specify a version, when you download the PDF, the document will be appended with the version number automatically.
• Whilst the Assist system is being adopted, these documents should be held in the standard development or project document folder - please consult your project or product documentation for details.