Documentation Template & Guidelines

Owned by Jaime Taylor
Last updated: Mar 18, 2022
3 min read

Descriptive Title

and subtitle if necessary

Created by [name of person or group], date

Updated by [name of person or group], date

 

FOLIO apps & permissions necessary for the task. If you do not have the required permissions, please contact [title, name, email].

Non-FOLIO tools necessary for the task, if any (e.g. MarcEdit, Connexion, Excel).

 

Related or dependent workflows: with links to those documents. 

 

  1. Step one: tell us which FOLIO app or other tool we are starting with. 

  2. Consider including screenshots or other images. 

    1. Images should illustrate what you are doing in a step. 

    2. If screenshotting a whole screen or window, use arrows or circles to highlight relevant buttons, fields, or other parts.

    3. Buttons should be circled or highlighted by mousing over. Menus should be clicked open. We want to know what in the image we using.

  3. What do we do next? Do not assume what might seem like basic knowledge or that the worker will know sub-steps you haven’t told them about. 

    1. We want workers to be able to carry out the task even if they do not entirely understand it yet.

    2. Therefore, give details & offer explanations. 

    3. Did you skip something between steps? Don’t! Staff need to be able to move from step to step without having to infer something between them.

  4. If we are working with data outside of FOLIO, tell us where we can find that data, what file type we should be using & how the data should be formatted. 

    1. Is it a .txt file? Is it comma separated? Tab delimited? JSON?

    2. Perhaps include an example of what the file contents should look like. 

  5. Keep the worker oriented – tell them where in FOLIO they are for each step, especially if the screen has changed (e.g. the three-panel UI opens or closes, a new window pops up, you switch to a different application). 

  6. Tell us what the expected results of actions should be. If applicable, tell us what to do if we get other than the expected results. 

  7. If you need to refer to an institution specific workflow or detail, include a link to it in the appropriate step. That link should go out to a document in the institution’s space on the Confluence site. For example:

    1. If you are at Smith College, click here for details on how to do this. 

    2. If you are at UMass, click here for the file path options. 

    3. Please actually make the documents on the other side of those links!

  8. Don’t get too in the weeds! Details are important, but too deep a dive will result in staff getting lost. 

  9. Are there common mistakes that should be avoided? Uncommon but REALLY IMPORTANT mistakes to avoid? 

    1. Tell us what they are & why they need to be avoided.

    2. Tell us how to avoid them.

    3. Tell us how to fix it if we make a mistake, or who to contact for help.

  10. Follow the Style Guide & keep accessibility in mind. Refer to the Glossary if needed.

  11. Be consistent! Call features & tools by the same name every time you refer to them. Use capitalization, punctuation, quotation marks, and other formatting consistently throughout a document and between documents. Formatting should help orient the reader.

  12. When the workflow is complete, tell us what the outcome should be.

 

Notes: Include at the bottom any FYI or FAQ type information that didn’t have a place elsewhere. You can put things down here that are good to know but would be a bit in the weeds if they were included in workflow instructions.