Who are kiara's users?

[caro401]

We need to define some clear personas of people who will use kiara, and by extension these docs, and for what purposes. This will inform what docs we need to write.

The distinction I'd initially made between an end-user/researcher and a developer is apparently incorrect, so the proposed structure needs re-doing to match these personas.

It's probably worth documenting somewhere (in these docs) who the personas are, so users of the docs can understand where they fit in (if they do), and therefore which parts of the docs are relevant to them. We should also summarise this in either the overview, or the 'is kiara right for you' section

[caro401]

One view of who kiara's users are and which parts of kiara they all care about is represented here:

This is generated from https://github.com/DHARPA-Project/kiara-personas, and was established in ~ November 2022. This doesn't capture anything about a user interface over Kiara, which may or may not currently be a current end goal for the project

[caro401]

This diagram sort of maps to the current docs personas, in that

• current 'researchers' ~= 'Modules/Pipelines Users'
• current 'developers' ~= 'Modules/Pipelines Creators' and also 'Pipeline-Apps Creators'.

The initial terminology was a poor choice, in that everyone probably identifies as a researcher. A better distinction/terminology would be 'end users' vs 'developers/programmers'

As we currently don't really have anything to support the 'front-end developers' persona, I initially omitted them, but we should definitely add docs that address their needs. I'm not sure whether this would make sense grouped with the other developers/programmers docs, or as a separate section of tutorials and how-tos

[makkus]

In my mind, at this stage, the main target audiences are end-users, and plugin developers. For the first group its difficult to create documentation, since we don't have a product yet. The tropy mini app would be our first, so probably we need to work with placeholders here.

Getting everything together that is important for developers who want to create kiara plugin is probably the most meaning-/useful thing we can do in the beginning. Esp. if it's done by someone that is not me, since I am not in a good position to judge what is important, which is why I would suggest to do this 'top-down', and try to figure out what we want to document (how to create a module, how to create a data type, how to create a pipeline), and then work through it and pick up all the concepts and things along the way that are un-intuitive or not documented yet.

Then there is the target group of 'us'. One thing I was hoping to get out of this project is a structured space where I can fill in documentation about more internally important things we don't want to expose to users (at least initially). Stuff like why things are the way they are, what we tried that did or did not work, that kind of things.

[CBurge95]

For me, 'end-user' still feels a little vague - what is their coding ability / domain knowledge? What platform are they using to access kiara, and what does this mean in terms of accessibility? (UI? Python? CLI?) There is a huge difference in who the end-user is simply based on what coding ability and experience they are expected to have to be able to use kiara. If the goal audience is dh scholars wishing to work more reflectively, or traditional hums scholars looking to learn/develop, then the more computationally complex the end user is expected to be, the less likely they are to use it. Obviously this question comes in at a junction of both technical and theoretical expectations of the project.

The idea of a plugin developer is important, but how many of those will we achieve (beyond the team here) if there is not an established entry-point user? How will they know how to / that they should develop plugins if they are not first sure how to use them?

I understand there is a trade-off in terms of being able to do everything if we go UI (aka mini-apps) only or at least predominantly, but the control we gain in being able to pin/control dependencies & the larger audience in terms of accessibility and usability is a huge benefit, in my opinion.

[caro401]

Does it make sense to distinguish 2 kinds of end users, and target all our efforts to those groups initially? In my mind, one group is exclusively UI users, and the other is users of the Python API, which includes people writing python scripts, using Jupyter and also me doing UI things. These are distinct from plugin developers/internal people working on kiara itself.

• UI users would need (some) conceptual docs (what/why is reproducible research for example), lots of the examples grounded in existing scholarship or existing tools as discussed from Mariella's research, and eventually something about how to find, install and use any UIs we create. Their section of the docs shouldn't really include any code, and we could assume they know their own domain, and something about digital methods? These are who we should focus our efforts on initially, but also there's not so much concrete writing work we can do for them yet?

• Python API users would need more (and more technical/detailed?) conceptual docs (what's the store etc), and examples of how to do specific things using the existing python API and plugins. We could assume they know their research domain, more about the digital methods, and enough python to be confident(ish) writing scripts/notebooks. Selfishly, this is what I need right now to be productive in making the hypothetical UIs. We can do this writing now, but the target audience in the future will (hopefully) be a lot more limited, once the UI exists.

Does that fit with your idea of who the end users could be and what they might need from docs (and eventual products) @CBurge95 ?

If so, could we think of meaningful names for each group, and maybe think about defining a (UX) persona for each group, to represent the target person we're writing for? (apologies for tech jargon, hopefully linked article kinda explains what I mean by a persona in user experience (UX) research)

[makkus]

and the other is users of the Python API, which includes people writing python scripts, using Jupyter and also me doing UI things.

Sidenote, and just a guess, but I think you'll be using quite a few more and different API endpoints, and need to be way more familiar with the concepts surrounding them then someone who only wants to implement a workflow from top to bottom. The latter is probably pretty much 'run_job', 'store_value', access Python data from value. Maybe do some look-ups on module/operation metadata.

My experience with frontend prototypes kind of points towards the other stuff around the edges (previews, selecting data, event handling, how to divide into reusable UI components) will take up a much larger percentage of the code and effort, compared to submitting/running a job and doing something with the result directly in Python.

Could be wrong though. If I'm not, then it'd make sense to split up those two use-cases. Or maybe build the one on top of the other or something.

[caro401]

Start with documenting the bits of the API any python API user will need? I need those too! And if there's spare time, I can add extra bits that fewer people are likely to need. I probably trust python API end-users to work out which bits of the API they want to use, and not get scared off by functionality existing that they don't need, but I don't trust UI-only users to not get scared off by a bunch of Python

[makkus]

Well, obviousy the UI docs should not be mixed with Python code. Just pointing out that there are 2 levels of Python docs and if we are thinking about things like how to name variables in our examples and don't use the term 'api', I'd have assumed splitting documenting things that a 'normal' research user would never use and the core stuff that everyone uses might be a reasonable idea. The 'advanced' stuff could potentially be fairly confusing to someone who doesn't know what an api is (in the same vein that we decided to not mention queue_job for example).

[CBurge95]

In my mind, one group is exclusively UI users, and the other is users of the Python API, which includes people writing python scripts, using Jupyter and also me doing UI things.

For me this makes the most sense. I also think having them separate - in terms of technical documentation/aims & goals - might be helpful in terms of achievability (at least in the short term).

I'd have assumed splitting documenting things that a 'normal' research user would never use and the core stuff that everyone uses might be a reasonable idea.

I also completely agree with this! I am fairly adept at 'skipping' bits I don't need to know, but it would be helpful to have these two levels of docs so that newbie coders (I include myself in this) can distinguish between 'I don't know this and I don't need to know this' and 'I don't know this but I need to at least conceptually understand how it works to be able to use this product'

In my mind then there are three levels of documentation/development, that result in the two 'end-user' types/personas, that can be followed in a certain order:

1. Python coders/API users for UI development (aka Caro)

This feels the most important at the moment, to be able to kick start some of the other stages. Getting a) enough API and core structure documentation and b) enough stable core modules to be able to start making mini-apps. Again (at least at this point) this won't be for an end-user, it just needs to be enough that others within the team can learn how things work and start building on that - in a sense making a distinction between full/proper documentation and just having information that can then at some point be turned into documentation.

2. UI users

(Speaking exceptionally naively in terms of technical requirements for this) this seems the most natural/stable option for the first end-user goal, that hopefully doesn't require too much support or 'pivot' in terms of how kiara is already built and what it can currently do. Especially if we are envisioning the mini-apps in terms of a particular pipeline (with potentially some flexibility in terms of the order that operations are done in, but with one main research goal from A to B in terms of Tropy / network analysis / topic modelling), we can push support & development to focus on these specific goals, rather than the hypothetical everything possible scenario. User-documentation (aka how to use rather how it was built) can be fairly simple as well, pulling mostly on the metadata/instructions already built into the modules.

3. Python coders/API users as end-user

This seems both the most difficult to achieve in terms of development and documentation and the most work, especially if this necessitates a pivot more to kiara as a python library (as in #6 ) This is obviously not to say that it is not a core goal/end-user, but that it should come last in terms of the order in which things are done. Obviously some of the things necessary to the first two steps - API documentation, stable core modules - overlap and work towards this end-user, but there are many more steps in terms of documentation and functionality. I also think that a Python end-user would be comfortable using a UI, but not the other way round, so it doesn't make much sense to me to focus purely on this end-user, in terms of achievability/usability (at least in the short term).

In the mean time, we can still work on the basic documentation for this in terms of using and building modules - acknowledging that things might change, but that in creating some of this now we can introduce more stability and consistency (both in terms of code and documentation, as in #10 ). @MariellaCC am I right in saying that the documentation you are interviewing for/writing is for the python end-user, rather than the UI one? Or a mix of both? For me at the moment the idea of your documentation work at the moment is fundamental in helping us take stock of what exists and what needs to be done to achieve goal 1 and 2!

[makkus]

Yes, thanks @CBurge95 , that's pretty much what I meant to say, but you did it better. Another thing to mention is that we can reasonably expect to have to explain less to the first group (so we can take for granted that users know about type hints, and what the difference between non-blocking 'queue_job' and blockinng 'run_job' is and why it's important), while in my experience, for the 3rd group you can't really expect any common knowledge maybe apart from having created a dataframe at one time or other (as we realized, we are concerned they are puzzled by the use of the word 'api', which kinda hints at how much we expect without even thinking about it), so we have to decide how far into 'intro to Python & best practices' we want to stray. Ideally we wouldn't have to, but for the doc to be useful it's probably necessary to do some.

Obviously, there is some overlap, which is why I mentioned maybe we can build the docs for the 1st group 'upon' the one for the 3rd earlier. as a strategy. Still, we have to be aware of those different target audiences.

[CBurge95]

Agreed, for sure. I think for general introduction to python we can easily link to external introductory information, but say at the start that there are a certain level of pre-existing knowledge we expect (depending on which documentation they are looking at) and whether we can explain these in docs or if they require more knowledge, where this can be found. I'm also more than happy to act as a check-in as lower-technically-able (but probably fairly representative of the humanities DH coding ability) if words/terms/concepts do or don't make immediate sense.

[MariellaCC]

am I right in saying that the documentation you are interviewing for/writing is for the python end-user, rather than the UI one? Or a mix of both?

@CBurge95 Yes, I agree. I also see one scenario where Python end-users would also be users for community plugin-related UI prototyping: Streamlit users (streamlit is a UI creation tool aimed at Python users. So I can imagine that some users may be developing Kiara modules/pipelines via community plugins and creating a streamlit app to provide a UI dashboard for the community plugin). This is the category that was named "Pipeline-Apps creators". At the moment, however, we did not specifically try to see if there would be some users interested in this. This would also differ from the more general scoped professionally created mini-apps for official plugins, with a wider potential audience (proper UI versus a more restricted scope prototype/dashboard in Streamlit).

[caro401]

Everyone seems to have slightly different groupings of potential user groups with slightly different names, and different ideas about who exactly these people are and who should be prioritised when.

Please can we define some concrete personas ((UX) personas) for all the possible target audiences we may ever care about? Then we can all agree on names for these groups, and on who we need to prioritise first. When we propose or write a bit of documentation, we can also reference exactly which persona(s) we are writing for.

I don't have enough expertise in the background of the project to do this alone, although I'm happy to facilitate creating personas in a group, or throw some incorrect assumptions in a pull request as a starting point to be corrected.

These personas will definitely evolve with time in the project, but I think clarifying who we've imagined right now, and getting a shared understanding among the team about who we are working for will be really helpful.

@CBurge95 I guess you and @stakats are most expert in who these personas should be? Would this exercise be helpful to you, what's the best way to proceed here?