Write the Docs
A proposed methodology for documenting Library Workflows
Created by Bobbi Fox / @bobbi_fox_SMR for ABCD-Library, 26 June 2017
Acknowledgements
This presentation makes liberal use, with permission, of the "Write the Docs Bootcamp" at the Code4Lib New York State, 2016, meeting, presented by Gillian Byrne (@redgirl13) and Christina Harlow*
*Translation: I'm basically stealing it
What is WritetheDocs ?
““There exists a tribe of documentarians in the world. Up until this point, they haven’t had a central place to meet each other, and coalesce into a community. We are providing the space to allow this to happen, both in person and online.
“The time for all technical people to care about documentation is now. We’ve lived too long with awful instructions for the tools we use everyday. People should demand solid instruction of things that they use.”
-- http://www.writethedocs.org/guide/about/vision/
But that's for techno-geeks!
While the Write the Docs community started by focusing on developers and engineers, information professionals can still leverage the work: information and data are part of Library work!
Why Write Documentation?
- We forget. Colleagues forget. Data/code/workflows don’t help you remember.
- We want others to be able to use our stuff.
- Generally, we want to help people.
Documentation makes our stuff better
because:
- It forces us to think it through when we document.
- We may write tests/examples/diagrams that we wouldn’t otherwise.
- Others can now comment or give feedback more meaningfully.
- It may break functional silos.
For Whom?
End to End Workflows
Make it so that all the actors involved in a workflow can understand:
- Timeframe
- Deliverables
- Hand-offs
- Expectations
- Roles
For Whom?
Multi-dept. Projects.
Ensure all internal stakeholders for a project are on board with:
- High level view with areas of overlap
- Clarification of departmental expectations
- Avoid duplication of effort
- Point persons for various portion of project
- A record project of decisions (or of department decisions that affect the project)
For Whom?
Data Profiles/Specs
Users + Consumers of our (meta)data, including:
- Discovery System Indexers
- Repository Developers
- Manual Creators / Collection Specialists
- Batch Processors
- Data Aggregation/Sharing Systems
For Whom?
"For myself" is a perfectly good answer
Principles for Documentation
Start Simple.
- Use plain text.
- Follow a basic template.
- Work with tools that can take that text & generate a web or document view.
Principles for Documentation
Consider Version Control.
- How will you track changes?
- Don’t shy away from "coding tools" for documentation file versioning.
- Consider what is the ‘canonical’ documentation.
More complex documentation
With more complex documentation, you also need to think about where to include the documentation:
- On a "shared drive"?
- On a wiki? And if so, which one?
- On some part of the Library website?
More complex documentation
What are the limitations of where you put the docs?
- Are certain systems required by the department?
- Is this public or private information (or both)?
- How maintainable is it, and who will do that?
More complex documentation
With bigger projects, you have even more questions:
- What gets documented where and by whom?
- Who to keep documentation up to date?
- Who triggers systematic reviews?
- Who can decide what becomes "legacy" when?
Building Docs Buy-in
Also called "mindshare" by WriteTheDocs folks.
For documentation to be worthwhile, we need:
- People to use it;
- People to believe it;
- People to write it;
- People to upkeep it.
Building Docs Buy-in
1.State the Problem.
(Preferably, do so simply.)
Building Docs Buy-in
2. Start in an area where you already have agency to change/update.
(No need writing docs for that other department)
Building Docs Buy-in
3. Gather input/feedback.
(And you'll see the importance of version control here.)
Building Docs Buy-in
4. Create a Documentation Taxonomy.
(Answer the perennial ‘where do I put this’ question.)
Building Docs Buy-in
5. Make the documentation easy to use and to add to.
(Templates, Templates, Templates.)
Building Docs Buy-in
6. Have regular check-in meetings throughout the project/work.
(If applicable.)
Building Docs Buy-in
7. Maintain, Rework, Update, Use, Refer to, & Regularly Review Your Documentation.
(In other words: the hard stuff.)
What to Write?
- Know your audience
- Know your problems
- Know your context
What to Write? -- Code focused
- Example(s) of usage
- Key or major features
- Installation or Quickstart
- Tutorial
- Links to code/data/tool & issues
- How to get help
- License for code/data
- Changelog
- Cookbook
- Community Information
- Contributor Information
What to Write? -- Metadata focused
- Properties/Fields with Labels
- Object or Data Model
- Namespaces (esp. for Reuse)
- Notes on Format, Encoding
- Mappings
- Expected Values, Obligation
- Domain/Ranges (if RDF)
- Target Applications
- Diagrams
- Data/Ontology License
- Changelog, History, Contacts
What to Write? --Dept. Projects focused
- Teams / Team Point Persons
- Teams Roles & Scope
- Timeframe
- Project Requirements
- Esp. those 'baton handoff’ items
- Deliverables
- Portion workflows
- Check-in points, questions
- Overviews of work for sharing
- Scope
What to Write? -- workflow focused
- Scope
- Roles
- Timeframe
- Requirements
- Hand-over points
- Where to get help
- What to do when things go wrong
Where do we want to go from here?
Coda
As a result of the discussion, I have created a "straw horse"
template proposal
Thank you!
(This presentation was created using reveal-js)