Documentation Framework Discussion at Hydra Partners - March 2013

Owned by Bill Branan
Jun 16, 2017
2 min read

From: Karen Cariani <karen_cariani@wgbh.org>
Date: March 28, 2013, 7:57:08 PM EDT
To: "libdevconx@mailman.stanford.edu" <libdevconx@mailman.stanford.edu>
Subject: [ldcx] Documentation notes
 

Documentation

Not knowing what you don’t know…….requirement list of technologies you should have under your belt before you begin implementing a hydra head
Requirements of knowledge – is there a list?  Is it out of date

 Get wiki regularly updated
In software – something that can spit out

Partly about training
Partly about listin gout gems

Solr, Ruby, Rails, git hub, git, fedora in addition tohydra…..

            r-spec, RVM

List on wiki duraspace hydra/developers

Make more prominent
Swap out capybara for cucumber

How long would it take to ramp up?

Knowledge skills need to be more prominent for managers – not under developers

Unification of the documentation is problem

If something is broken take it down?  Who does that?

            Or put it somewhere and say it’s old

Have all docs and copy when a new release feel free to purge things out of date – but potentially leave breadcrumb to older one.

Doc Syncing strategy

            Version docs with code

Are we documenting all the code? A functional walk through of the tutorial process and other changes in this version – need both

Take down currently outdated documentation

Lots of doc is currently in git hub
Lots of links are broken and don’t know where it’s wrong

 If something isn’t obvious you explain it

Tie it into the release process

Part of release process is creating a new guide or fixing/updating the old one
Ok with removing old stuff as long as there is a process to make sure the old one is wrong

Get rid of old stuff if we can distill it into a good version

Add to release managers things to do to remind folks to think about documentation and whether new code is still adequately reflected in documentation

Lifo – how the rails community goes about documenting
Have a separate documentation site – now they are tied to git commit

Merge wikis between duraspace and git hub
Move development documentation to git hub – someone needs to do it
Point people from old space to new home
Communicate that it is under construction while it is happening

What would a document for version 6 look like?

            4 paragraphs of implementation

Hydra modeling conventions?  What’s that about?

More of an evolution of thinking about the project than about what to do

Some of the pages are informative but not so much if you don’t have a clue. 

Is there a better mechanism to flag problems and get community feedback to fix it?

Is it possible to set aside some time to talk about documentation.  Tie it to the release process going forward.  Have a doc fest like a hack fest – 1Ž2 day to go through documentation and make decisions and update docs.  In Boston?

Hydra camp curriculum – how does this tie in? Should consolidate for training and workshop- so others can learn on their own and others can teach the camp- make sure it works before starting a training

Have the tutorial that is being maintained is the one being used.  

Actions
  • Update list of knowledge required
  • Identify and nuke stale docs
  • Version docs with code
    • Have own repository for documentation
  • Tips, pointers, best practices
  • Migrate developer documentation from Duraspace to git hub
    • communicate the move
    • request time boxed approval
  • Documentation audit and automation at Boston mtg (1/2 day)
  • Module of what I need to know as a manager - documentation