# User Problem

## User

Any user working with long-lived documents that involve multiple steps and/or users.

## Problem

As a user I need to create, edit, organise and find documents that relate to my projects.
I need a rich integration with the objects such as workpackages and meetings to organise the actual work.
I need rich meta-information on the documents - like status, version, history, -  so that I can define and follow workflows for the documents.
I need co-workers to have access to the documents based on our roles in the projects. 
I need to be able to apply these same processes to files that are created and edited in other tools (csv files, images, ...).

I need to have an intuitive and modern editing experience.
I need to collaborate with co-workers in real-time on documents.
I need to have AI tools to assist me in text editing, but also in turning texts into other formats such as work packages.

## Pain

Organising multi-step workflows with multiple users for a document with tools that are not built for this purpose. Additionally, media breaks in the workflow and lack of integration with workpackages and other artefacts causes additional work.

A classic example is the file that gets shared via email, copied and renamed multiple times to create new versions. In the end, users have a hard time finding the right version, seeing the history and can't even be sure that they have the exact same content as their co-workers.

<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/755740/content">

<br>

Instead it should be something like this

<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/755741/content">

<br>

# Business Case

## Reach

Everyone has this problem to some extent.

## Impact

On average a I assume a medium impact for users. I think it will have a huge impact for users that need to work with very long-lived documents with complex work-flows. For other users the impact will be fairly small.

## Confidence

Confidence is somewhat low as we do not have users with a strong need within OpenProject GmbH and have not conducted user research.

## Urgency and Priority

This has high priority as we need a richer documents implementation as outlined above to enable/improve workflows with documents as input or output.

## Solution

Create a new documents model, making use of the existing rich collaboration and workflow features. Additionally the editor will be replaced with BlockNote and using Yjs/Hocuspocus to get real-time collaboration  as well as integrating AI features.

## Differentiation

Direct integration into the project management software and workflow oriented features combined with a modern text editing experience.

# Roadmap

## Version 1

##

#### List of documents (Index)

* Columns for Name, Type, and Last Edited

* Search titles

* Filtered views by Types in left hand menu

* ~~Sort by table columns~~

* _Leave this out of version 1, as Design team wants to do more work to design this in general so it can also be applied to workpackages for example._


#### Clean View (Distraction free)

* In this view the focus is on the text being read/edited and there are very few elements apart from that main content

* Sidebar collapsed so the content is completely centered horizontally

* Default for opening a (collaborative) document

* directly editable

* Only contains

* the main content

* the title (edit in place)

* the type

* active collaborators


#### Detail View

* detail view can be enabled/disabled, it adds further elements to the clean view, for now it will only contain

* Attachments

* Design to extend to other things we add later (Activity, Versions...)

* Collaboration

* Project permissions determine access control to document (no document-level permissions yet)

* **\[Simultaneous editing (via Hocuspocus and YJS)\]**


#### Migration

* Begin of the insertion_~~**DECISIONEnd of the insertion Begin of the deletion _**DECISIONEnd of the deletion NEEDED, Begin of the insertioneither**~~**:**_End of the insertion Begin of the deletion either:**_End of the deletion

* Turn existing categories into types, documents into collaborative documents and add files as attachments

* Begin of the insertion~~IgnoreEnd of the insertion Begin of the deletion IgnoreEnd of the deletion existing documents, migrating them later into file based Begin of the insertiondocuments~~End of the insertion Begin of the deletion documentsEnd of the deletion

* _**TASKS:**_

* Test migration to see how well it works

* Design safety feature to ensure data is not lost


#### AI assistance - STRETCH GOAL

* **\[Summarise\] - STRETCH Begin of the insertionGOAL #**End of the insertion Begin of the deletion GOAL**End of the deletion


#### **\[Text to action\]**

* Reference and visualise workpackages (like current macros with ## but also the new / command)

* also transform links to workpackages

* **\[ (Batch) create workpackage from text\]**

* Create a workpackage by typing /wp, then selecting the type, then entering the title and confirming with enter

* If this is done in a list/enumeration, the next item should also start in the workpackage creation flow

* Create a workpackage list by typing /wp-list (eg. like in the Paris Hackathon &#39;list mode&#39;)

* Select a list and create a workpackages from each item in the list, replace item with work package reference

* Reference documents from work packages (eg. with the # approach in CKEditor or the / command in BlockNote)

* _Note: Allowing users to choose the type of workpackage, brings additional challenges because the type may not be valid without certain fields, the subject may be automatically generated. In addition it will not be as smooth to display the status as it is the case of task which has a boolean status (checked / unchecked)_

* _Note:_ _Maybe the /keyword needs to be configurable? This extension could be used outside of OpenProject (OpenDesk, elsewhere) to invoke the OP-specific dropdown._


#### API

* We have an API and need to make sure we don&#39;t break it. The strategy to achieve this will depend on the migration decision

* _Note: The existing API only provides GET for documents, simplifying this significantly._

* How can this work with YJS documents for creates and updates

* _**TASK: we need to research/prototype how we can do this.**_


#### Rename Categories to Types

* _Note: because we&#39;re not introducing Status yet, on the surface this is just a rename - even if we create a larger change and migration underneath._

* As long as we have not migrated the existing documents, it will be necessary to use the type to differentiate between a collaborative blocknote document and the old documents

* ALTERNATIVELY the differentiation could be based on an attribute on the document itself - may make migration easier as well.

* _**NOTE: There is a way to configure Categories, we&#39;ll need to adapt it to Types.**_


<br>

##### _Additional Notes_

_**\[Description\]** denotes a feature that will make people care. The other features are basics that are needed but do not inspire._

_Collaboration is supposed to be the main focus, but we need to carefully decide which features to include to get a great result without taking a very long time to achieve it_

##

## Further versions (WIP)

### Collaboration (WIP)

* Document can be shared with specific people

* Document visibility can be restricted (only invite, private, ...)

* **\[Inline comments\]**

* with threads, in notification center, ...

* General comments

* @mention users

* Watchers

* Notifications for mentions/comments on Notification Center and emails


### AI assistance (WIP)

* **\[Text to Task\]**

* Mark some text and let AI create a suitable task (bug, feature) with a good description.

* **\[Summarise\]**

* **\[Transform text according to user instructions\]**

* **\[Translate\]**


### Integrations (WIP)

* Integration with

* Docs

* openDesk Notes

* XWiki


### Workflows (WIP)

* Types

* Types determine which statuses are available for a document

* Predefine useful types

* Define types based on existing categories

* _**QUESTION: What about statuses here?**_

* Versions


### **File based documents (WIP)**

<br>

### **Other (WIP)**

* **\[Outline\]**

* Quick filters for Index

* Notes


# Launch and Growth

## Measures

_?_

## Messaging

Edit documents collaboratively in OpenProject.

From text to action

<figure class="table op-uc-figure_align-center op-uc-figure"><table class="op-uc-table"><tbody><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Headline</p></th><td class="op-uc-table--cell"><p class="op-uc-p"><br data-cke-filler="true"></p></td></tr><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">First Paragraph</p></th><td class="op-uc-table--cell"><p class="op-uc-p"><br data-cke-filler="true"></p></td></tr><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Customer Quote</p></th><td class="op-uc-table--cell"><p class="op-uc-p"><br data-cke-filler="true"></p></td></tr></tbody></table></figure>

## Go to market

?

_How are you planning on getting this into users&#39; hands?_