Kiara Documentation

This page should appear as the homepage for kiara docs, and should make it clear to any potential user what kiara is, and why they might want to use it, even if they’ve never heard of kiara before.

some of this content is relevant?

Something along the lines of using data and digital techniques to do research is a good thing to do, but…

Keeping track of where your data came from and what you did to it is hard because

• writing and versioning code is hard?
• jupyter makes it easy to lose track of what you ran when?
• keeping records of where you got your data from is hard?
• you might need to use lots of tools/programs/languages and import/export your data a lot?

kiara helps with all of these things by

• you don’t have to write (much) code
• everything is a pipeline, so you always know what steps ran when on what data
• and your pipeline encodes everything about the process, so its repeatable and shareable
• all in one tool to do all tasks, with lots of plugins, easily extensible to your domain

Use kiara to solve your problems like

• i’m a researcher and i just want a nice way to show how i got the data together for my open data set
• i lead a research group and i want to share easy and repeatable ways to do common tasks within my group and more widely
• i’m a techincal domain expert and i want researchers to be able to apply methods i know about to their data

About these docs

A possible information architecture for a new docs site for kiara could look like this.

• Overview/summary/homepage draft and ideas

• I’m a module user

  • Tutorials/getting started - for network analysis folks and NLP folks
  • how-to specific things - some ideas in /users/how-to-<something>.md
  • how to install python

• I’m a plugin author

  • Tutorials/getting started making a plugin and making a pipeline
  • how-to specific things - some ideas in /developer/how-to-<something>.md
  • something about developing on kiara core

• I use kiara via mini apps

• I develop kiara itself

• Concepts

  • Glossary/explanation of terms
  • Something about data lineage and reproducibility
  • overview of kiara architecture
  • something to explain when kiara might not be a good fit?
  • How kiara does versioning

• List of known plugins, summary of what they do, link to/include their content-based docs (see below)

• autogenerated API Docs (the content for these exists already in the Python code)

  • CLI docs? like what this page promises? or like a man page.
  • kiara.core already exists here
  • other core plugins like tabular, network analysis - are there others?
  • link to/include api docs for other plugins

This structure is loosely modelled on the diataxis framework for writing and structuring quality documentation. This also has really great ideas on how to structure the individual pages that fit in each section

General considerations

Search

Good search will be really important, especially if these docs get big and/or the information architecture gets messy. Great if the tech solution we choose already has search built in (mkdocs-material does for example), else pagefind is a nice option.

Docs from plugins

There’s a bunch of different types of plugins, core vs not, made by us or external people, just workflows or complicated things. At the very least, I think these docs need to list what these plugins are, if they are public.

If there’s tutorials or how-tos specific to a plugin, it might be nice to also include them here, encourage plugin authors to PR the docs repo as a way to publicise their plugin and what it does.

Plugins always need a way to have API docs. The existing mkdocs solution from the template could use some work. It’s as yet unclear whether the eventual ‘main’ docs site should directly include docs for some/all/no plugins, or they should be standalone.

Testing

How do we make sure these docs, specifically the how-to’s and tutorials, are correct and also remain up-to-date if/when kiara changes? Wrong docs is almost worse than no docs, so getting testing in place is really important. Are there existing tests for any docs or notebooks?

miscellaneous questions

• Do we want to show API docs for packages at specfic versions, or only latest?
• do we want to support (now/in future) multilingual docs
• Should we have a writing style guide? Do we make our own, or take a pre-exiting one? Can we enforce it. Same for formatting of markdown files etc.
• is it worth visually distinguishing docs aimed at researchers vs developers? use-case: I’m a historian and I found a page via search, but I don’t understand anything on it, is that because i’m stupid, or because those docs aren’t relevant to me