Documentation Best Practices

Last Updated: October 14, 2022 9:29:03 AM PDT

Find guidelines on options for where to create and store documentation for UC San Diego audiences.

Before creating any documentation, check with your department/co-workers/other sources to make sure it doesn't already exist. Include only specifics and link to the source material, thereby reducing bloat and streamlining content size.
Be consistent-create and maintain similar documentation in the same place.
Be organized-follow naming and formatting conventions.

Blink

Blink is the "intranet" for UC San Diego faculty and staff though it is public (not behind a login). If your information is for all or most employees, put it in Blink.

More information: https://blink.ucsd.edu/go/cms

CMS Websites

Departments and centers can create websites for public facing content. If your information is for a specific audience, place it in a CMS site.

More information: https://blink.ucsd.edu/go/website

Services & Support Knowledge Bases

The Services & Support portal, built on the ServiceNow platform, includes knowledge bases (KBs) for each audience. This is a great place for specific "how-to's" and frequently asked questions. Each KB has it's own group of editor/approvers. If you're interested in creating knowledge base articles, check with your department's approvers or submit a ticket on the appropriate portal.

More information: https://blink.ucsd.edu/go/support

Confluence (collab)

Confluence is a platform for Wiki and project management content. Most spaces require an AD login. This is the best place for ITS and ITS partner project documentation as well as information that needs to be behind a login. Note: Access does require a license.

SharePoint or Google site

Both SharePoint and Google sites are good place for content that is specific to an audience, such as a department, or content that needs to be shared with everyone at UC San Diego (everyone with a campus AD account).

More information:

OneDrive or Google Drive

Both Google Drive and OneDrive are best for hosting and collaborating on documents. Access is behind AD and can be granted to any campus individual or AD. It can also be shared UC San Diego (everyone with a campus AD account).

More information:

For questions or assistance with any of these options, contact wts@ucsd.edu

Note: this page has a friendly link that is easy to remember: https://blink.ucsd.edu/go/documentation