Documentation To Dos + wishlist

[mialondon]

Some initial headings and hooks for documentation are at https://github.com/chnm/serendipomatic/wiki but it needs a lot of work... This will also become the start of the 'pre-flight checks' that we'll run through before pushing from dev to live.

UX/design/tone things to document

• [ ] Graphic elements design guidelines (icons,
• [ ] Tone guidelines for micro-copy, error messages, etc
• [ ] Official (purchased) font, fallback fonts and text style guidelines
• [ ] Page style guides - margins, responsive flow, etc
• [ ] Colo(u)r schemes and use of colour for different types of message, emphasis

  Developer things to document

For some of these things we can point to existing resources, others will need project-specific documentation

• [ ] How to get the code set up on your machine
• [ ] How our 'go live' review process works
• [ ] How to get changes live onto dev for review
• [ ] Who's monitoring for errors and how do they decide who they're passed on to?

  Project vision

• [ ] What kinds of resources do we want to add/prioritise? See also https://github.com/chnm/serendipomatic/issues/126
• [ ] Is Serendip-o-matic about primary sources from GLAMs or does it include scholarly publications from journals etc? (though obviously for printed material 'primary' is relative
• [ ] How do we bring individual GLAM etc repositories into the mix? e.g. how are they weighted, how many?
• [ ] How might a 'hint' function (discussed on wiki) relate to the mix of sources presented on the results screen?

These are just starting points, questions from everyone will help us work out what needs to be documented so please go for it and add things...

[mialondon]

Would love to hear from Outreach and PMs to help pull out information lurking in dev/design heads - it's so easy to forget to explain something but we'll lose our tacit knowledge really quickly so prompts to document things would be useful. @JackDougherty @briancroxall @mfrazer @amrys @rpalin

We'd also benefit from CHNM experience here so @patrickmj @foundhistory could you pass this on as appropriate?

[mialondon]

Some input to the Project Vision section - various museums are keen to be included (via twitter and email conversations). And there's also this twitter conversation:

https://twitter.com/petrknoth/status/364670758003294208 Petr Knoth ‏@petrknoth '@briancroxall Seen your Serendip-o-matic. Fancy feeding it with 12M+ open access articles from CORE http://core.kmi.open.ac.uk through its API?'

Do we want to broaden the scope beyond museum, library, archive content as primary material? What about archives from other organisations - e.g. I've asked people I know at the BBC to think about what material they might have.

[briancroxall]

@mialondon What sort of tacit knowledge do we need to try to pull out of dev/design heads? And what is the best way that we can go about doing this? Asking tons of questions? Getting you guys to talk and then transcribing what you say?

[mialondon]

The latter is easier, IMO, especially since you're in the same place as @rlskoeser but both work.

Starter prompt questions for different functions: how does this work? What inputs does it expect? Can you recall any workarounds that ended up in code? What did you try that didn't work? What slipped out of scope as we ran out of time? Is there any testing you have a feeling we should apply to this area?

[mfrazer]

I'll help here however I can...maybe I can touch base with some of the other developers.

[mialondon]

Meghan, that'd be great! And I suspect there are probably lots of things that I don't know I need to get out of my head, so include me in the people you ask questions of.