Here we will provide some background and history of the Fred Hutch Biomedical Data Science Wiki.
Why we started
This project has evolved out of efforts by staff in both scientific and administrative realms at the Fred Hutch to streamline guidance, communicate the current state of resources and generally learn from each other, circa 2016. To do this, we needed a collaborative tool that could both get down to the nitty gritty of details and code and links on a variety of topics, but also render it into something more digestible to the general public. While many of our links to go to internal documentation that is only accessible by our own staff, we also wanted to provide both guidance for how this effort could be done elsewhere, and also share what we can with the wider, public audience. Given also that the primary content providers and creators of this project were not web designers, we realized that perhaps a GitHub based repository with a remote theme created by a real designer could work for us. We have relied upon Micheal Rose’s minimal-mistakes theme, though we certainly have made many mistakes while this project evolved!!
How we write
We were very interested in creating an easy to maintain resource, but while those of us supporting resources see the documentation as a group of unrelated documents, those of us USING those resources often cut across a variety of those resources in our day to day work. For content providers, it’s much easier (and thus more likely to be done frequently) to document things in one place per resource. However for content consumers it’s much easier to have “on-ramp” style documents that may ease them into the gory details while teaching them along the way.
In an effort to minimize duplication, reduce stale content, and simultaneously balance the content consumer’s need for on-ramps, we aimed to create the following types of documents:
Articles use an outline structure to allow graduated content, starting from basic information and progressing to more detailed content for expert users/readers. Using headers (H2 through H4) in the text allows the automatically rendered Table of Contents to facilitate readers’ ability to jump around the documents to get to needed content as well as the creation of anchors to allow for linking directly to portions of content in a longer page. By keeping related text together in a small number of pages, it allows us to provide more context for people who are learning about a topic, allows finding of other related information a reader might not have known to look for, AND allows content providers to manage content in ONE PLACE rather than spread throughout the site.
This site is created by researchers and staff who are not web designers nor technical writers by training! Thus, we have opted for a relatively flat organizational structure to keep it simpler for content curators and to reduce the risk of information becoming stale and irrelevant as much as possible.
Resource Library Entries
The shorter, more focused, Resource Library entries can use headers as well to population the Table of Contents. These documents are intended to be fairly detailed examples or content that is linked to by Articles, but address a specific use case or example scenario that may be only intended for advanced users/readers. Once a number of related Resource library entries are created, Editors may consider consolidating the information and moving it into the main site as a full Article to highlight the content to new readers.
External Example and Template Repositories
These are mainly explained and linked to from an article page in our site. Basically we hope to highlight work contributed by others both at the Fred Hutch and elsewhere by linking to the resources they have put out into the world.
Both Articles and Resource Library entries are full-text searchable using the search feature (the magnifying glass in the header), however the External repo’s are not. This search ability is the primary strength behind this Wiki and will be the primary way people will find content, as, again, no web designers or technical writers are involved in this grassroots project.
Over time we have experimented with a variety of search providers and ways of indexing content. Now that we have built a structure and are moving toward the maintenance phase of this project, we are focusing more on making our resource make more sense to readers. We are using Google Analytics and user feedback primarily to figure out if this resource is “working”. If you have suggestions or notice weird things when using our search page, please file an issue in our GitHub repo and tell us!!! We hope that users can GET to the info we have provided when they need it but it’s hard to know if that’s happening, and also, did we mention we aren’t web designers??
We also encourage contributors to leave their mark as well by adding their own contributor page here. Researchers in training in particular have referenced this project as evidence of their science communication experience and technical writing chops. We encourage more scientists to branch out in this way, while also learning a lot to help them in the short term.
Currently we have our documentation regarding instructions for how to contribute in a handful of places. Please, if you have an opinion about how and where in the site you think this information is best consumed, file an issue in our GitHub repo and tell us!!!
Our GitHub README.md has the main overview.
Our newly emerging Content Providers page will have a publicly digestible version of that content and on-ramp style documentation about how to contribute to a documentation site. So meta!!