Post on 12-Oct-2020
File Name REF-INT_Ascena_SSG_Documentation_Standards
Document Owner Michael Wilson Document Approver
Effective Date TBD Review/ Revision Date 10/7/2016 Reviewed by
Ascena SSG Documentation Standards
Description Documents the process for creating new and updating existing documentation for the Ascena SSG. This also
provides detailed documentation standards for creating documentation within the Ascena SSG
Keywords Documentation Standards, Style Guide, Template, File Naming Conventions, Word Document Properties, Style
Tags, Documentation Procedure, Documentation Process, How to Write a SOP
Overview
It is important to make sure that either your intro or your description explains exactly what the document covers and possibly why and when you need it.
Topics
This document covers several topics, including:
Documentation Process
Document Section Definitions
Process Documentation Template Tags
Call Out Text Boxes
Document Naming Conventions
Using the Document Properties Feature in Microsoft Word
Purpose
Defines the steps, tasks and information required to create, update and publish an SOP.
Defines the template styles tags and when you use them.
Defines when you need to use Note, Caution and Danger text boxes.
Establishes document naming conventions to help locate relevant documents faster.
How to use the Document Properties feature in Microsoft Word.
Audience
All Ascena Retail Group Shared Services employees, contractors, consultants and managers.
Documentation Process
2 of 16 Ascena SSG Documentation Process and Standards
Documentation Process
The documentation process for the Ascena SSG consists of several phases:
Identify Documentation Needs
Gather Information
Validate Information
Writing the First Draft
SME Review
Writing the Final Draft
Sign-Off and Publication
Identify Documentation Needs
There are several factors that should be considered when identifying and prioritizing documentation needs:
Audience – You need to define who will be reading/using the document as clearly as possible. Gather information about the audience’s job description, technical knowledge and skills, and work experience.
Business Need – This defines the business objectives for the document. This information is used in the Purpose section of the SOP.
Scope of Document – This information outlines the scope of the document you are about to create. The goal is to break down each major task into small, manageable parts. This section should list what specific tasks or actions that need to be documented.
Assumptions/Exceptions – This section sometimes is included in the SOP. Assumptions defines any assumed knowledge necessary in order for the document to be useful. Exceptions outline situations where the process defined in the SOP is not followed.
Gather Information
The Subject Matter Experts (SMEs) locate any information related to the process and compile it for the SOP draft. This information may include:
Old SOPs, process documents, or reference materials.
Rough drafts of a process flow.
Details about step-by-step actions taken while performing tasks described in the documentation needs definition.
Screen captures of actions and processes taken while performing the described tasks. Some examples of the kinds of information to capture are:
New screens or windows, system messages
Error or warning messages
Forms that have important fields filled out
Any other action where an illustration might be helpful for understanding the process being documented.
Documentation Process
Effective Date: 10/7/2016 3 of 16
You can use screen capture software such as SNAG-IT or Skitch, or use the [CTRL] + [PrtScn] and paste the screen capture into MS-Word or an image editing program and crop it down (if necessary). You can either copy and paste these images into a Word file or save these screen captures separately in a JPG format.
Data entered into system such as information entered into blank fields, menus, selections from drop-down lists, buttons or tabs selected, etc.
Keystrokes of commands entered into the system.
Output displayed by a system or application as a result data entered or action taken.
Critical information or warnings about any actions that might be confusing or cause any serious problems.
Lists of common problems or issues encountered during the process (along with the solutions).
The information gathered is assembled in the form of a draft document and submitted to a designated Infrastructure team member for review and validation.
Validate Information
1. The designated Shared Services Lead reviews the document to validate that it is complete and correct, and addresses any issues that the Lead might encounter with the technical SMEs (i.e. the Offshore Team).
2. The Shared Services Lead sends the draft document to the Technical Writer to begin writing the first draft.
Writing the First Draft
1. The Technical Writer takes the validated information from the Infrastructure Lead and creates a first draft of the document. This includes the following:
Importing it into the standard documentation template.
Editing the content for completeness, clarity and consistency.
Applying paragraph and character tags to the content to improve readability.
Formatting the screen captures and/or illustrations to fit on the page properly and captioning each of them.
Noting any information gaps, questions about the content, and any other information or content that might need to be added, deleted or changed. These notes go back to the Infrastructure Lead to drive additional information capture or validation.
Adding keywords and descriptions for the SharePoint search capabilities.
Submitting the draft document into SharePoint, following the standard file naming conventions.
2. Finally, the Technical Writer sends the SharePoint link for the completed draft to the Shared Services Lead for validation and clarification.
Documentation Process
4 of 16 Ascena SSG Documentation Process and Standards
SME Review
1. The Infrastructure Lead addresses all of the questions and open issues with the applicable technical SMEs and then reviews and validates the draft for correctness and completeness.
2. Once this has been completed, the SME posts a revised copy of the document into SharePoint and notifies the Technical Writer.
Writing the Final Draft
The Technical Writer incorporates all of the information from the Infrastructure Lead, and completes the following tasks:
Proofreads the document a final time to catch any problems that might have been missed in earlier drafts.
Checks the screen captures for clarity, usefulness and that they appear correctly on the page. The Tech Writer also makes sure that every screen capture has a caption.
Checks the layout and look of the final document making sure that there are no page breaks in bad places, verifies that all style tags have been correctly applied and that the text flows logically through the document.
Updates all of the references on the first page, the headers and footers.
Creates links or a TOC (for documents longer than 10 pages) for the Overview section (if necessary).
Converts the MS-Word file into a PDF format.
Sign-Off and Publication
1. The Technical Writer checks the final document into SharePoint.
2. Sends a link to Austin Pritchard and/or Gonzalo Cubelo (or their designates) for final approval.
3. After receiving final approval, the Technical Writer posts the document as Published and notified the applicable audiences (if necessary). Both the MS-Word and PDF versions are saved in SharePoint.
Document Section Definitions
Effective Date: 10/7/2016 5 of 16
Identify Process to be Documented
Gather Information
Data Entered – Fields, Buttons, Menus, Drop-
Downs, etc.
Keystrokes/ Application Output
Screen Captures (Take a screen capture of major processes,
new actions, etc.)
Action Steps
Submit request to Offshore
Team
Key information, warnings about confusing steps or
possible dangers
Offshore Team submits info to Infrastructure Lead (Michael
Kirkpatrick)
Inf. Lead reviews & validates info from the Offshore Team
Inf. Lead hands info off to the Tech Writer (Michael
Wilson)
Tech Writer enters info into the Template and
applies Style Tags
Format screen captures for consistency
Enter document Keywords, Description,
Reviewer, Filename, etc.
Enter the document into
SharePoint under version
control
Send Inf. Lead the SharePoint Link
for draft validation and
addressing issues
Enter questions, comments, issues and
clarifications
Inf. Lead reviews draft,
addresses issues
Makes change suggestions and
saves to SharePoint
Sends final draft to Austin/Gonzalo
(or their designates) for final approval
End of Process
Tech Writer makes updates and posts the
doc in SharePoint
Infrastructure Documentation Process Flow
Last Edited: 4/13/2016Document Owner: Michael Wilson
Figure 1 – Example Documentation Process Flow
Document Section Definitions
Every document should have the following sections information contained on the cover page:
Overview – (Optional) Provides a high level introduction of the information contained within the document. This shouldn’t be longer than a sentence or two. Sometimes the information provided in the Description of the table at the top of the cover page is good enough.
Topics (if applicable) – Longer documents will have a list of the Heading 1 topics as a list of hyperlinks so that the user jump to the section that they are interested in. Very long documents might incorporate a Table of Contents. This section will not appear in all documents.
Purpose – This section explains exactly what the document covers, and possibly why the information within is provided and when you need to use it.
Audience – Who the document has been written for. This can range from a general audience to a specific department or group, or a list of job descriptions or roles within an organization.
Process Documentation Template Tags
6 of 16 Ascena SSG Documentation Process and Standards
Cover Page Header
Header – This is the white lettering on the blue background at the top of the table. This should be automatically populated by the text that you entered in the TITLE field in the DOCUMENTATION PROPERTIES section (typically on the right-hand side on the File tab).
Description – This provides a high-level overview of the information contained within the document. The table automatically populates the text entered within the SUBJECT field in the DOCUMENT PROPERTIES section.
Keywords – This is where you enter any search terms that a user might enter to find this information. Enter as many relevant keywords as you can. These search terms can be process, hardware, software, department or descriptions of the information within the document. Be sure to enter other related terms that a user might use to search for specific information.
The table automatically populates the text entered within the KEYWORDS field in the DOCUMENT PROPERTIES section.
For specific details on how to set up these fields within the DOCUMENTATION PROPERTIES, go to the Using the Document Properties Feature in Microsoft Word section.
Cover Page Footer
File Name – The name of the file as it was named when you saved it. Auto populated field.
Effective Date – The date when the information contained within became active (if applicable)
Document Owner – The person who wrote or was responsible for providing the information within the document. This field is auto populated with the information entered in the AUTHOR field in the DOCUMENT
PROPERTIES section.
Document Approver – The person who approved or signed-off on the document (if applicable). This is usually the person who requested the document.
Review/Revision Date – The date when the document was last reviewed or revised. This field is auto populated to display the date the document was last saved.
Reviewed by – The person who last reviewed the document’s contents for accuracy or changes.
Process Documentation Template Tags
The Process Documentation Template has been configured to allow the user to generate documents that have a consistent look and feel, without needing extra effort on the authors creating documents.
The Paragraph Style and Character Style Tag sections below define when you use the common paragraph and character styles within the template. These sections do not cover all of the styles created within the template.
Paragraph Style Tags
Paragraph style tags format a block of text that continues until you press the [Enter] key. These tags have been formatted to use the same font, text color, indentation, numbering (or bulleting) format, and spacing between paragraphs. The examples of the paragraph style tags used in the template are provided and explained in this section:
Process Documentation Template Tags
Effective Date: 10/7/2016 7 of 16
Heading 1
Use the Heading 1 tag for main topics, or sections with many sub-topics underneath them. The text entered using the Heading 1 tag automatically appears in the header of each page (except for the cover page).
The Process Documentation Template Tags heading above is an example of a Heading 1.
Heading 2
Use the Heading 2 tag for sub-topics to help organize the information. A typical use of a Heading 2 tag is to label a sub-process.
This is an example of a Heading 2 tag
Heading 3
Use a Heading 3 tag to divide up a sub-section into information blocks.
This is an example of a Heading 3 tag.
Heading 4
This heading is rarely used except in very complex process documents.
This is an example of a Heading 4 tag
Body
This paragraph tag is used for most of the main content that is not bulleted or numbered. It is the basis for the Bullet and Step tags.
This is an example of a Body tag
Bullet 1
The Bullet 1 tag is used in any sections that do not use a Step tag or are indented in any way.
This is an example of a Bullet 1 tag
Bullet 2
The Bullet 2 tag is used if information needs to be bulleted after a Step tag or indented tag has been used previously in the document.
This is an example of a Bullet 2 tag
Bullet 2 Indent
This indents the text to line up with the text formatted with a Bullet 2, but without a bullet.
Bullet 2 tag
This is an example of a Bullet 2 Indent tag
Process Documentation Template Tags
8 of 16 Ascena SSG Documentation Process and Standards
Caption
Captions are inserted to describe the content of a screen capture or other illustration, or table.
Figure 1 - This is an example of a Caption tag
Placeholder
Placeholder tags are tiny paragraph tags that rarely have text in them, but serve as a “spacer” to make sure that HTML formatting before and after illustrations, tables or text boxes do not get messed up during the .MHT file conversion process.
This is an example of a Placeholder tag
Step 1
The Step 1 tag is the main tag used for numbered, sequential processes. The tag automatically numbers the next step when it is applied over several paragraphs.
4. This is an example of a Step 1 tag
Step Indent
The Step Indent tag is used when supplemental information needs to be included for a process using a Step 1 tag, but does not need a new number. This is used for closely related or important information associated with a specific numbered step.
5. Step 1 tag
This is an example of a Step Indent tag
Table Text
This tag only applies to text which is within clearly defined cells in a table. This tag is designed to make sure that the information can be easily read within the context of the table. This tag also needs to be applied to text box cells containing icons so that the spacing on the table appears consistent.
This is an example of a Table Text tag
Table Bullet
Bullets used within a table can be difficult because of the limited space available within a table, so a separate bullet tag is needed to ensure readability for the table.
This is an example of a Table Bullet tag
There is also a Bullet 3 and Bullet 3 Indent tag in the template in case it might be needed..
Process Documentation Template Tags
Effective Date: 10/7/2016 9 of 16
Table Header
The Table Header tag labels the table data. This text is white in heading cells which have dark shading.
This is an example of a Table Header tag
Character Tags
Character tags are style tags used to highlight important words or phrases within the content of a sentence or paragraph. These tags make it easier for the reader to identify critical information such as text entered into the system by the user, field names, document names, etc. These tags format this selected info as an exception to the formatting already established by the paragraph tags.
Button
This tag highlights buttons on a web-interface, or can represent a key pressed on a keyboard. Keystrokes are surrounded by brackets. For example [Enter] or [F4]. The text using the button tag should be identical to the button as it appears on the interface.
The Button tag is also used to represent a tab in a GUI. For example: Select the Options tab.
This is an example of the Button tag
Edit-Comment
The Edit-Comment tag is used by the author or editor within the context of a document to ask questions or provide feedback to other writers or reviewers. These comments are also enclosed in brackets.
This is an example of the [Edit Comment tag].
Field Name
The Field Name character tag is one of the most common tags used in our documents. It identifies fields that require input from the user or contain important information for the user.
This is an example of a FIELD Name tag.
Field Option
This tag is used to display any pre-determined values that may be selected for a particular field, such as through a drop-down list or radio button selection.
This is an example of the FIELD OPTION tag.
Hyperlink
This is an active link to another document.
This is an example of a Hyperlink tag: http://spot.nwie.net/site/iam/iam/IAMint/SitePages/Documentation%20Development.aspx
Call Out Text Boxes
10 of 16 Ascena SSG Documentation Process and Standards
Menu
The Menu tag is used to show navigation through a series of drop-down lists or to navigate through a series of directories.
This is an example of the Menu tag: FILEPREPAREPROPERTIES
ScreenName
The ScreenName tag is used to identify the names of unique pages in a Web GUI or windows in an application.
This is an example of the ScreenName tag.
System Display
The System Display tag displays output from an application so that it can be easily differentiated from User Enter Text. The output of an application is critical to many steps within a process.
This is an example of the System Display tag.
User Enter Text
This tag identifies text entered by the user via a keyboard or other user interface.
This is an example of the User Enter Text tag.
Variable Text
In many situations the documentation will not be able to provide the exact keystrokes necessary to complete an action because of the variability of how a particular system works. Information such as login IDs, server names, and passwords need to be entered as part of a command in order to assure that the application works as intended.
All Variable text is also surrounded with angle brackets <> which are not entered as part of the variable data encompassed within.
This is an example of the Variable Text tag: <CLASS>-<CATEGORY> <DESCRIPTION>
X-Ref
The X-Ref tag represents text that serves as a cross-reference to another location within the current document. It is used to rapidly navigate between different areas within the same document.
This is an example of the X-Ref tag.
Call Out Text Boxes
These text boxes highlight important information that needs special attention within a document.
Call Out Text Boxes
Effective Date: 10/7/2016 11 of 16
Information Call Out
The Information Call Out highlights information that is helpful for the user to know when performing a task. This might be a suggestion or a helpful tip to assure that the process goes smoothly.
Caution Call Out
A Caution Call Out brings attention to information that is particularly important because it might disrupt or prevent the completion of a particular task. This might also point out when an action (if performed incorrectly) may result in problems for the user, other team members or the organization itself.
Remember to brush and floss regularly or your teeth will rot and fall out.
Danger Call Out
The Danger Call Out highlights information that definitely disrupts the completion of a task and may result in problems such as data loss, complex application errors, difficult to diagnose troubleshooting issues, or significantly impacts service to the customer, other groups within Ascena or the company as a whole.
Pressing this button will wipe out all of human civilization as we know it. DO NOT
PRESS THE RED BUTTON.
Provide an existing IP address to compare it to serve as an example.
Document Naming Conventions
12 of 16 Ascena SSG Documentation Process and Standards
Document Naming Conventions
Type
A document type is a broadly defined type of document that can be created for any project. Most documents will be classified as PRJ (Project) or REF (Reference).
ID Description of Document Classification
ADM Administrative document such as a status report, project spreadsheet, or unique internal process
DEV Development specific documents such as requirements documents, test plans, architecture documents, etc.
DIA Network diagram or business process diagram
PRJ This is a project-specific document.
REF Reference document, this is a document used to store reference information such as a list of important links,
servers, etc.
REQ Requirement document
SOP Process document, typically a step-by-step sequence or a standard operating procedure
TMP Template
TRG Training document
VEN This is a document created by an outside vendor and which is not updated by members of the Ascena team.
Category
A document category typically represents a technology or service type. A process defining a new application or project typically is assigned a unique 2 to 3 letter category identifier. These might be unique codes for specific project names or for a particular brand.
ID Description of Service Offering Category
ECOM eCommerce Project
FMW Middleware Group
INF Infrastructure Group
INT Internal document
ITSB Infrastructure Technology Standards Board
JST For Justice retail stores
Document Naming Conventions
Effective Date: 10/7/2016 13 of 16
ID Description of Service Offering Category
NWK Networking Group
RAX For Rackspace documentation
SSG Shared Services Group
TBD To Be Determined
Brief Description
The Class and Category codes are followed by a couple of keywords that describe the contents of the document. The description should contain at least two of the search terms you would use to find information about the problem in a SharePoint search.
Date
Most documents under version control do not require a date in the filename. If you need to note the date of a particular document for some reason, insert the date that the document was last revised in the following format: YYYY/MM/DD.
Document File Name
This is the format for a typical document file name:
<TYPE>-<CATEGORY>_<DESCRIPTION>_DRAFT--<DATE>*
* If applicable
Do not use spaces between words in a file name. Use an underscore (_) or a dash
(-) to keep the filename continuous.
Using spaces for filenames creates longer hyperlinks in SharePoint, making them
difficult to read, and, in some cases, too long for the search features.
Here are some examples of how the naming conventions work together to form a unique Document ID
REF-ITSB_Architecture_Requirements
PRJ-INT_eComm_Project_Standards_DRAFT–-2015-06-02
SOP-SSG_Using_SharePoint_User_Guide–-2015-06-12
The DOCUMENT ID is identical to the file name of the source document.
If the document is not under version control, insert the word DRAFT in front of the date.
Documents under version control do not require this since the draft status is already
configured in SharePoint.
Using the Document Properties Feature in Microsoft Word
14 of 16 Ascena SSG Documentation Process and Standards
Using the Document Properties Feature in Microsoft Word
One of the keys to making the documents easy to find when performing searches within SharePoint is using the Document Properties feature in Word to add critical information such as the title, a detailed description, and keywords into the document.
To fill out the Documentation Properties fields in a new document:
1. Click on the File tab in the upper left-hand corner of the Quick Access Toolbar.
The application displays the Information about the Word document.
Figure 2 – MS-Word File Tab
Using the Document Properties Feature in Microsoft Word
Effective Date: 10/7/2016 15 of 16
2. Go to the Document Properties section and click on the SHOW ALL PROPERTIES link.
Figure 3 – Word Document Properties Section
3. Complete the following fields:
AUTHOR – The person who created or initiated the creation of the document.
TITLE – This is the reader friendly name of the document without underscores or dashes separating the words. Keep the wording of the title very similar to the filename.
SUBJECT – Write a brief description of the document contents, especially if the TITLE does not spell out important specific details or if the TITLE might make it possible to confuse it with other similar documents. The text entered into this field populates the DESCRIPTION table on the document’s cover page.
KEYWORDS – Enter any words that might be entered as search terms by a user searching for this document. Be sure to list application names, hardware names, actions necessary to complete a task, target audience, problem or error messages, again anything that makes the document easy for you to find.
MANAGER – Enter the name of the person who is the DOCUMENT REVIEWER or DOCUMENT APPROVER.
Using the Document Properties Feature in Microsoft Word
16 of 16 Ascena SSG Documentation Process and Standards
4. Save the Word document.
Related Information
Ascena SSG - Master Document Template
Ascena SSG - Master Document Template (Landscape)
If all of the fields listed above don’t appear in the Document Properties section, click on the
Property Views and Options dropdown in the upper right-hand corner of this section and
select Document Properties from the list. These fields should now be displayed.