ascena ssg documentation process and standards · file name...

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.


2 of 16 Ascena SSG Documentation Process and Standards


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.


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.



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.



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


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.



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.


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:



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



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..



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


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


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.




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



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.




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



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.



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.

http://epm01/pwa/tech_standards_board/Documentation%20%20Templates%20%20Standards/REF-TMP_Ascena_SSG_Document_Master_Template.dotx

http://epm01/pwa/tech_standards_board/Documentation%20%20Templates%20%20Standards/REF-TMP_Ascena%20SSG%20Document_Master_Template_Landscape.dotx