Documentation Working Group Notes

Owned by Bill Branan
Jun 16, 2017
9 min read

Documentation Working Group
Hydra Connect 2
Friday, 10/3/2014
The Unconference
10:45-12:15

Introductions

  • Joseph Rhoads (Brown):

    • Digital Repository Manager: part manager, part developer

    • At Brown, they primarily program in Python/Django

    • Thinks it hasn’t always been easy to figure out where to go to find information about using Hydra, more information would lower the barrier to entry

  • Patrick Etienne (Georgia Tech) - Facilitator

    • Digital Library Developer

    • digging into Hydra can be a bit overwhelming

    • curious about what the strategy behind the documentation is, and if there is one

    • wants to know what are people thinking as far as solutions for documentation

  • Mark Sellan (Washington University in St. Louis)

    • Manager, Systems Administration and Networking

    • thinks there are some really good Hydra docs out there, but you get stuck when you can’t find something

    • once upon a time he was a technical writer; is happy to help improve the documentation but not sure where to dig in - wants to find out who is the core group for documentation in Hydra

  • Steven Ng (Temple University)

    • Digital Library Applications Developer

    • while digging into Hydra, discovered that the documentation was sometimes out of sync with where the development was

    • would like to help contribute, but wants to know what the process is and how the documentation can stay up to date

  • Shannon Davis (Washington University in St. Louis)

    • Digital Projects Librarian

    • wants to discuss how can librarians help create documentation, which is one of their strong skills and could be a great way for those not on the development side to make important contributions to Hydra

  • Andrew Rouner (Washington University in St. Louis)

    • Digital Library Director

    • a question involved in knowing where to start in Hydra is knowing where to find feature lists, solution bundles, and core Hydra projects - should the locations of those items live in the documentation somewhere? maybe there should be a spectrum of documentation - from code documentation to other kinds of information that might be suited for for people who are considering Hydra - both types of documentation are needed

  • Wendy Hagenmaier (Georgia Tech) - Note Taker

    • Digital Collections Archivist

    • Like Shannon, interested in finding out about how those who aren’t on the development side could contribute to the Hydra Project through documentation (archivists are obsessed with documentation)

    • also interested in how documentation can help non-developers dig into the development side more, so they can “dive into Hydra,” develop a common language with developers, and help support the community

Discussion

  • It can be good for non-developers to write documentation or test it to ensure that it is clear

  • Lack of documentation can be a barrier to entry

  • When documentation is out of sync with code, it can make things very difficult

  • We need documentation to know what the core projects are and where and what the features are

  • Sometimes the people who end up writing the most documentation are the people who are new to the project - documenting things is a learning aid, it helps you figure out what’s going on - this seems to be a trend in Hydra but also in other open source library projects - and then, once those beginners get up to speed, they end up working on something new or not working on documentation at all

  • Maybe people who are new to Hydra could be more directly involved in documentation, and there could be a clearer path for participating in documentation

    • It seems like it’s important to make sure people understand that the wiki is there to be edited - to not feel like it’s a read-only, intimidating interface (how can we communicate that virtually, through the documentation itself?)

  • It seems crucial to capture the pain points (areas/steps where things are confusing and there is no documentation or there isn’t enough documentation to help) involved in working with Hydra, so that even if you can’t fix them or troubleshoot them, they are documented - so others can help address the pain points or so you can troubleshoot them later - maybe we could add pain points to the Issues in GitHub and label them “documentation” - if it’s something that’s solved, you could write that it’s solved and provide the location of the answer/where the improved documentation lives

  • Question: What is the documentation? Where does it live?

    • Wiki

    • GitHub (various places)

    • Google Groups

  • Question: What is the relationship between the wiki and GitHub?

    • The wiki sort of lives separately from the code - is that what we want?

  • Documentation often happens after the fact (after code is written, after an event happens), and if the documentation is not co-developed, it’s not as useful - it’s best to develop documentation along with the code and to create documentation in a similar way to the the way code is developed - check in and check out system - documentation should be ticketed

  • In the Python world, they use readthedocs - readthedocs.org - links the code with the documentation - is there an equivalent tool for Ruby - maybe rubydoc.info ?

  • As a new person exploring Hydra, it can be difficult to get the lay of the land (for example, what is a “hydra head”?) - the high level information about Hydra could be clarified too - it seems like there is a need to find a way to reconcile the way the project is described with how the code is described (this comes back to the “solution bundle” vs. “repository development framework” question/ambivalence that seems to exist within Project Hydra and which was discussed during the opening panel session)

  • Documentation written in Markdown could live in the codebase - a Jekyll instance could be automated from the code repository, so documentation could start living next to code - could be searchable and editable via tools like prose.io - this could lower the barrier to entry

  • It’s good to have documentation live where you would expect to find it. For example, something like:

    • higher level, non-technical documentation could live on the wiki

    • technical documentation for each Hydra project could live with the code

    • and code should be written in a way that is self-documenting, as well

  • Could GitHub Issues for Hydra projects be flagged (flags in themselves are a form of documentation) to identify fairly straightforward problems that need to be solved? - these flags could offer good starting points for those who are new to Hydra and want to learn by fixing small things

  • Maybe we should canvass the community to find out what documentation is needed - perhaps via a survey - and organize the community feedback? Maybe non-developers could review the documentation?

  • Question: How is the Hydra wiki arranged? What is the method to the madness?

  • One thing that would be useful to have on the wiki is a page that lists the tools people use in working with Hydra (such as JIRA) and the workflows for using those tools

    • could include information about Markdown, editors

  • How divided should development and management documentation be? How distinct will the roles currently involved in most Hydra projects be in the future? What are future Hydra roles and how do they affect the way we should design documentation?

  • We’re sort of talking about documentation-driven development - sort of like use case-driven development - related to test or behavior-driven development

  • User stories seem to be key as shared documentation for both managers and developers

    • it seems important to document your strategy at a high level and then breaking that down into user stories using Gherkin and Cucumber - so that you have layers of documentation

  • Are user stories available to the community? Where is the user story work being done?

    • If they’re created in Cucumber, they will be found in GitHub; there is a product called Gitnesse (runs as a gem to publish Cucumber to a wiki)

    • But that’s only if you’re using Cucumber - why do or don’t people use Cucumber? People often use it when they’re working with end-users and stakeholders

    • If there were Cucumber/Gherkin documentation published for each of the Hydra gems, would that be useful?* - would provide a consistent source of documentation to feed to wiki or a centralized location

  • Need to document the features available in Hydra and how they fit into the different gems

  • Question: What are the documentation requirements for official Hydra gems, and are they sufficient for the needs of the Hydra community?

  • Implications for documentation in terms of the long term vision for Hydra:

    • gemification of different Hydra projects - as Hydra projects become more granular, you’re really going to have to define the features and functionalities

    • Hydra wants more people to get more involved, to just jump in - you don’t have to ask (this applies to both code and documentation)

  • Question: What is the licensing situation for documentation?

    • Fixing documentation should be easy - documentation can always be rolled back to a previous version if there were ever a licensing problem

  • There may be a place for documentation in a wiki but maybe more documentation should exist with the code?

    • but coders sometimes get so busy that documentation falls by the wayside, so that the only documentation is in the code (self-documenting code)

  • Maybe the wiki is the narrative that glues everything together?

  • If the documentation is being peer-reviewed, perhaps anyone could write it as long as the stakeholder is involved to confirm that the document reflects what they wanted to create

  • Question: Who is responsible for the documentation - the developers or the managers? How can managers be empowered to do the documentation?

  • Maybe the idea of readme-driven development would be useful: http://tom.preston-werner.com/2010/08/23/readme-driven-development.html

  • Need for better connection between low-level coding documentation and high-level purpose documentation and a definition of the mission of each documentation level (and their respective locations)

  • Notre Dame’s agile process uses Gherkin - could we ask them to offer their model as an example for improving documentation?

  • Perhaps another role in the development process is the documentation point person for a sprint? - so that the spec of Gherkin-level documentation is up to speed and the Hydra wiki is updated as necessary

    • having someone like that may be more feasible for multi-institution collaborations or regional communities, not for small teams

    • could pull in non-coders for this role? how do you empower non-developers to document code?

  • Possible next step: Maybe we could do a survey to identify pain points and points of confusion or gaps in the existing Hydra documentation?

    • we could add the identified pain points as Issues into GitHub with label “documentation”

  • Possible next step: write suggested best practices (for local documentation and community documentation)

  • Need for documentation for those who are new to the Hydra community, such as a list of tools you should have in place when you start

  • Maybe the questions we’re discussing about documentation come down to:

    • Where? (where is the documentation and where should it be?)

    • Who?

      • Writers (who writes the documentation and who should write it?)

        • Metadata guidelines (written by non-technical people)

      • Readers (who reads the documentation and who should read it?/Who is the audience for each of the documentation pieces?)

        • Developers should read metadata guidelines

        • Audiences for the documentation:

          • Library executives/administrators - high level

          • Those with non-technical or managerial responsibilities

          • Those with technical or development responsibilities

      • Stakeholders

        • Those who are new to Hydra

        • Those who are very dedicated and invested in Hydra (the long-term community members)

    • What?

      • What are the minimum things that you need to provide to describe your project? - minimal viable documentation

      • Way to gather and publicize Hydra news (RSS?, newsletter?)

  • Possible next step: Write a feature matrix for Hydra (which projects have which features)

 

Action Items

  • Survey

    • Do a survey to identify pain points and points of confusion or gaps in the existing Hydra documentation

      • we could add the identified pain points as Issues into GitHub with label “documentation”

    • It seems crucial to capture the pain points (areas/steps where things are confusing and there is no documentation or there isn’t enough documentation to help) involved in working with Hydra, so that even if you can’t fix them or troubleshoot them, they are documented - so others can help address the pain points or so you can troubleshoot them later - maybe we could add pain points to the Issues in GitHub and label them “documentation” - if it’s something that’s solved, you could write that it’s solved and provide the location of the answer/where the improved documentation lives

  • Documentation definitions

    • define the purpose and scope of the existing Hydra documentation venues and methods

      • Wiki

        • develop a feature and project matrix (which projects have which features)

        • maybe wiki should be for data that is fairly permanent or changes rarely and could link out to GitHub code and GitHub pages (the documentation that would change often)?

      • GitHub

        • Determine workflows and best practices for documentation on the code (GitHub) side of Hydra

          • Explore defining suggested best practices for documentation, possibly including rubydocs, Cucumber, Gherkin, GitHub and GitHub Pages , etc.

      • Google Groups

        • next steps?

  • Documentation reviewers

    • assemble a group of volunteer reviewers to analyze and edit documentation

    • call for volunteers soon and organize the team after that

  • Get this group on the wiki

    • Create a Documentation Working Group area on the wiki (document the documentation, yo)

  • Schedule an open phone meeting in a month

    • schedule through a Doodle poll, invite all Hydra community members (including Hydra-Tech and Hydra-Community)