Documenting Systems / Sarah Sweeney

This study path guides the learner through close examination of system documentation by highlighting the elements of how to write and read the documentation for content management systems, in this case Mukurtu. 

By Sarah Sweeney, Digital Scholarship Group, Northeastern University Libraries

Learning Objectives

• Where you’re going to be at the end: At the end of this activity learners will be able to identify the elements of usable system documentation.
• What kind of path this sets you on: This activity will set learners on the path to better understand the elements of how to write useable system documentation.

Activity

Hands-on activity

Technical documentation that insufficiently describes a system or software may behave as a barrier that prevents external users from engaging with or adopting the system. This activity prompts students to review system documentation and identify what elements are useful or essential for understanding 1) how the documented system works and 2) how the documented system could be implemented. Using Mukurtu as a sample system, learners will find and review technical system documentation the Mukurtu team has made available to the public. Learners will consider the elements of technical system documentation, including major elements/sections/headings, information conveyed, requirements for understanding the information conveyed, audience, and others.

Smaller scale:

List of resources needed:

• An internet connected device

Starting from the Mukurtu website, find and review the Mukurtu system documentation.

Describe:

• The major components of the Mukurtu documentation
• What are the essential elements of Mukurtu’s documentation?
• What information does the documentation convey to users or potential users of Mukurtu? What might be missing?
• What information is required for system administrators to implement Mukurtu locally?
• Who is the audience for the documentation?

Identify one or two system elements that are not included in the Mukurtu documentation. How would you document those elements?

Resources

Readings

Case studies

Indigenous Knowledge Systems and Mukurtu CMS, Dr. Kim Christen ^[3]

Curricula

Social Justice though Technical Communication: Teaching Resources ^[4]