index.md

Kiara

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

• Overview/summary/homepage draft and ideas

• I'm a researcher

  • 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 developer/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

• 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