Formatting and Editing CSDP Documentation

Scope: This document describes the basic page edits made to documentation prior to a content edit.

Contact: Heather Baker

Unit: Metadata & Discovery Strategy

Date last reviewed: 06/12/24

Date of next review: 06/12/25

Table of Contents

Formatting

Initial Formatting:

• Once a page has been added by either uploading a Word document or creating a new page, click the pencil icon in the top right corner of the page.
  
  
• Before editing the body of the page, add the following to the space under the page heading. Make sure that the text is in bold and at the Paragraph level in the hierarchy found in the upper left-hand corner of the page. Fill in any known information about the following:

Scope:
Contact:
Unit:
Date last reviewed:
Date of next review:

• To add contact information, put the cursor next to Contact: and click the Insert link icon on the toolbar or click the down arrow next to the + and select Link.
  
  
• Select Web link in the left menu. In Address, enter the email address of the contact person. In Link text, enter the name of the person as it should appear on the page. Click Insert when finished. The name should appear as a blue, working link on the page.
  
  
• With the cursor at the end of Date of next review:, click the down arrow next to the + on the toolbar and select Horizontal rule from the list. This will place a line directly below Date of next review:. For easier reading, documentation content should be added below the horizontal line to create a separation between the document information at the top and the page content.

Style Edits

• Bold lettering, italics, underlines, and highlights: These may not upload or paste accurately. Use the editing toolbar at the top of the page (very similar to Word) for bold, italics, and underline. Confluence does not currently support highlighting text. The best workaround is to change the text color to red or use bold/italics/underline to draw attention to text. You can also put the content in a single-row table or add a panel. Instructions for using the Panel macro can be found here.
  
  

• Spacing: A hard return at the end of a line creates a double space. A hard return at the beginning of a line creates a single space. 
  
  
• Font size: You cannot choose a specific font size, but you can choose from the menu pictured below. These size choices will help you format to the desired size, but remember that the heading sizes will also determine the hierarchy in the Table of Contents macro, if used. Click here for instructions on how to add a table of contents.
  
  
  
• Wiki Markup: Text in an uploaded document may show up in a wiki markup box. If this happens, copy the text and right click to "paste as plain text" where it should be on the page. Delete the wiki markup box once the text has been pasted into the document. 
  
  
• Brackets: Brackets in an uploaded document typically show up in wiki markup format in Confluence. To edit this content, highlight the bracketed text (including the brackets) in the wiki markup area. Follow the Wiki Markup steps above. In Confluence, brackets are used to insert a macro. If you want to insert brackets as part of the text in the document, type [<escape>] and then move the cursor to inside the brackets to add text.
  
  
• Text colors: The text color palette icon has a limited selection of colors to choose from. To use a color not found in the color palette, follow these steps:

• • In Word, highlight the text in the the color you want to use. Click the arrow next to the text color button. Select More Colors. Note the RGB colors listed at the bottom under the Custom tab. Open http://www.yellowpipe.com/yis/tools/hex-to-rgb/color-converter.php and type in the RGB colors to convert to hexadecimal. In Confluence, add Markup macro.
    
  • Type {color:#[hex number]}[insert text]{color}. For example, 

    Collections Services is created by typing {color:#00B8D9}Technical Services{color} into the Markup box. Text should then appear in the color specified.

    
    

  • Here is a list of commonly used color codes:

    • Yellow: #FFE380
      Black: #172B4D
      Red: #FF8F73
      Duke Blue (dark): #17365D
      Duke Blue (light): #365F91

    
    
  • Additional color codes can be found here.
    
    

• Tables: Tables can be used to represent spreadsheets or highlight information. To insert a table, click the Insert table icon on the toolbar:
  

  
  

  • Select the desired number of columns and rows. A second toolbar of table options will appear. Use these to edit the table format. The top row of a table is always shaded as a header row. Click the header row icon to toggle between shaded and unshaded. The table can also be resized by dragging the row and column lines. 

    

• Table of Contents: It is helpful to include a table of contents if the document is very large. Detailed instructions for inserting a table of contents can be found here. Formatting the table of contents can be done by changing heading levels and adding or removing extra lines between headings and subheadings.

Images

• Images: Some images and/or parts of images do not appear when uploading or pasting content. This is when a side-by-side comparison is helpful. 
  
  
• To add an image or replace and incorrect image with a screenshot from the original document:
  
  
  • Take a screenshot of the original image. Save the image file using the document name, and number each image used in a document (e.g., style editing 1, style editing 2).
    
    
  • Click the Insert files and images icon (or Ctrl+M).
    
  • Click Upload files and select the image file from your computer. The image will appear as a selected image available for insertion. Click Insert.
  
  
• Formatting an image: Clicking on the image will pull up the available editing options.
  
  • Click Properties and select Drop Shadow. Then adjust the size of the image as needed by increasing or decreasing the pixel size on the left.

Page Links

• Page links are used when you want to be able to find a page in more than one place. Every document listed under Additional Resources on each parent page is a link. 
  
  

• To insert a page link, highlight and copy the URL of the page you are linking to. Go to the page that you will be linking from and click Edit.
  
  
• Place the cursor where you want the link to appear on the page and paste the URL (Ctrl+V or right click and select paste).
  
  
• A working link will appear in blue as the title of the page being linked to. Click Save when finished.
  • If the URL links to the DUL staff only page, the user will be prompted to log in.
  • If the linked page is moved to a new location within the CSDP, the link will still work and will not need to be updated.
    
    
• Each parent page has a link to the main DUL Collections Services page. The link appears in bold inside a shaded box. This is done by inserting a single-row table and adding the link inside the table. 

Reordering Pages

• If a page was incorrectly created/uploaded as a child page under the wrong parent page:
  • Open the page tree on the left side of the page. Find the page to be moved, but do not click to open it. 
  • Drag the page to correct location in the page tree.
  • Refresh the page for the change to be updated on the parent page.

• The page is now ready to be shared with the owner or team responsible for content editing. 
  

Best Practices

A few things to keep in mind when creating, formatting, and editing documentation in the CSDP:

• Add as much header info as possible
• Replace personal names with position titles
• Add labels but do not remove any labels
• After making an edit based on a Note to Reviewer in the header info, please delete the note once the edit has been made or the issue addressed
• Don't change document titles without notifying MADS