Overview

The goal of this epic is to let users interact with artifacts as if they are part of a document.

This can covers the following use cases:

• Requirement Management
• FAQs
• Meeting minutes
• ...

However, the primary use case is to address the Requirement Management needs, it will be the main focus of this first iteration.

Requirements management

Traditionally, requirements in Tuleap are managed as Artifacts. This is driven by the primary goal of the application: project and program management. In this context, Requirements (or other form of "description of what to do" like user stories) needs to have metadata, needs to be connected to concret form or work (code, deliveries, etc) and Artifacts are the best way to deal with that.

However, Artifacts are not easy enough in the upstream phase of Requirement lifecyle, when they are defined. Traditionally, it's more document based. It could be formal (like docx) or less formal (wiki) but the "free text" is often the preferred form.

Alas, having a document for the initial phase of definition and artifacts for the realization is often a trap: duplication, no single source of truth, differences between what is done and what was specified, etc.

We aims to address this issue by offering a way to write things as Documents but having them as Artifacts.

This is a new Plugin.

Permissions

• Plugin can be restricted per projects
• Who can see the document ?
  • Document readers as per Document plugin
  • Users who can read the target Artifact (Project permissions, Tracker permissions & Permissions on Artifact field)
  • Users who have read access on Title and Description fields on Artifact
  • User must have access to all artifacts (and the corresponding fields) to access the Document => Mockup: Error state cannot read.
• Who can write the document ?
  • Document writers can create the document and select the associated tracker
  • The ability to create Sections is driven by Tracker permissions. A user can create a new Section when:
    • They can access the target Project
    • They can access the target Tracker
    • They have Submit & Update permission on Title and Description fields.
    • There is no Required field other than Title and/or Description
  • User must be able to Submit & Update all artifacts of the document.
  • Mockup: How to distinguish read only documents.

Document

Artidoc is a new type of items in Document

• It doesn't have the full list of items capabilities at the moment. The only propose
  • Copy/Cut/Paste
  • Delete
  • Change properties
  • Change permissions
• On the Artidoc view itself, it's not possible to access item actions (edit permissions, etc). It's only available thru the explorer view.
  • However it's possible to edit document title

Steps

The entry point is in Document Management system (Document).

There is a new type of document “Artifact based” (a better name to be found). This new type of Document will be a collection of artifacts.

The collection is explicit. In this first iteration, it's associated to only one tracker, however, on the longer term the artifacts might come from several different trackers/projects.

Notes:

• associating one tracker to a Document is mainly a shortcut to ease the early interaction with the document like creation or selection of artifacts to embed in the document.
• An artifact can be embedded in several documents, however a document can embed a given artifact only once.

New document

At Document creation, the creator must select a Project/Tracker that will be used as reference. As mentioned above, at this stage, it is an helper.

When a new Artifact Document is created, it’s empty. Document writers can select artifacts to be added in the Document. The selector will propose artifacts from selected tracker (inspired from Artifact Link field with search ?).

Artifacts “Title” and “Description” are rendered as heading and paragraph(s). In the following text, “Title + description” will be referred as “Section”.

The order of the artifacts can be changed by drag’n drop in the table of contents. The corresponding sections are reorganized synchronously. The order of artifact is a property of the Document, it is not applied to global artifact ranking.

Artifact titles are automatically numbered (1, 2, 3, ...). Headings in the Description part of the artifact are not taken into account in the table of contents or automatic numbering.

Each heading (artifact titles as well as headings in document) have an anchor and can be linked.

TODO DESIGN: propose an alternative to drag’n drop for better accessibility.

Edit Section

When a Document Writer clicks on the text, the text can be changed right away (edit mode by default). The whole Section is toggled in Edit mode. The edition area covers the title & description of artifact. Both can be changed and there is an explicit “Save” action. There is a check to ensure that no data is lost on page leave.

The text can only be edited with the WYSIWYG editor and supports images copy/pasting. If the Description is stored in Markdown or Text, it's automatically converted to HTML at save time.

At save time:

• each section should saved one after another
• in case of error
  • backend throw a 40X or 50X => the error message is displayed and there is a "Retry" and "Cancel" button (to let user modify the structure of the tracker for instance) => Mockup needed
  • conflict (artifact updated in between) => the error message indicate that user is about to overwrite and have the possibility to "Force update" or "Retrieve the last version" => Mockup needed

Create new Section

At the beginning, at the end of the document, and between each section, it’s possible to create a new Section. A new section corresponds to a new artifact in the corresponding tracker and is automatically associated to the current Document.

At artifact level

At artifact level, users should have the information that the artifact is embedded in one (or several) document(s). => Mockup Needed

Metrics

We need to collect

• The number of documents created
• The number of view of a document

We need to find a way to sense if the documents are actually used. Maybe by counting if a document is viewed by more than one person ?

Todo / to decide / to clarify

• XML import / export
  • Be careful with artifacts outside currently exported project
• Actions on document (Log, Versions, Notifications, ...)
• Download as Zip
• Advanced search on type