Database Interop Hackathon/Documentation

From Evolutionary Informatics Working Group
Jump to: navigation, search

The Hackathon Documentation Team (Karla and Dave) have coopted this page to describe how documentation is being done at the hackathon. See the hackathon section of the Site Map for a complete list of hackathon related pages and documentation


Goals

  • Make sure the products of this hackathon are well-documented, either by cajoling or writing or both.
  • Make this wiki as useful as possible to help hackathon participants be maximally effective.

Subgroups

Each of the Subgroups has been assiged a specific doc person. See Subgroups for who your doc person is.

Wiki Organization

We've used a couple of guiding principles to structure the wiki.

Categories / Tags

Almost every page is categorized in two different ways:

By Content
These tags are based on what's in the page. For example, the CDAO and PhyLoTA tags are based on content.
By Source
Pages created for/by the Working Group have the Working Group tag, and pages created by/for the Hackathon have the DB Interop Hackathon tag. A notable exception to this rule is that most Data Resources are not tagged with either. These are important to both groups.

User Pages

Nominal user pages were created for each hackathon participant. These have at least category tags for the person.

To make linking to user pages easier, we also created pages for participants' first name that link to their user page. For example, typing [[Arlin]] will now add a link to Arlin's user page.

Hackathon Sidebox

Most pages created or heavily modified for the Hackathon also have a hackathon-specific menu box that appears in the upper right of the page. This can be added to your pages by typing this as the very first line on your page:

{{HackHead}}

Vignettes

Previous NESCent Hackathons (e.g., the Phyloinformatics Hackathon) used vignettes to document how to use the products of that hackathon. We're going to try and do the same this for this hackathon.

Vignettes are short code examples that show how users would use the outputs of this hackathon to solve problems (preferably problems they couldn't solve before). An example from the Phyloinformatics Hackathon is at Application: making bootstrapped data sets with PHYLIP.

These code-centric vignettes work well for Hackathon's with products that are entirely scripts or back end. However, some of our Subgroups are producing GUIs and those vignettes will take more thought.