Formatting and Editing CSDP Documentation
Scope: This document describes the basic page edits made to documentation prior to a content edit.
Contact: lib-mads-department-request@duke.edu
Unit: Metadata & Discovery Strategy
Date last reviewed: 06/12/25
Date of next review: 06/12/26
Table of Contents
In a separate window, open the original documentation. It is important to have the original document available for side-by-side comparison while editing to ensure that the formatting and editing of the CSDP page matches the original as closely as possible. There are often changes to spacing, numbering, and alignment when content is uploaded or added to the CSDP. |
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.
Tables: Tables can be used to represent spreadsheets or highlight information. To insert a table, click the Insert table icon on the toolbar:
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 Upload files and select the image file from your computer. The image will appear as a selected image available for insertion. Click Insert.
Remember to edit the image and add a description in the image in alt text
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