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.
• Which tracker can be used to save sections
  • Tracker must have a Title semantic and the target field must be a string field
  • Tracker must have a Description semantic and target field must be a text field
  • At most "Title" and "Description" fields are Required
  • Mockup: How to distinguish read only documents.

Document

Artidoc is a new type of item 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

Artidoc

Artidoc is a collection of Artifacts, the collection is explicit. It means that an artifact must be added with an action to an Artidoc. An Artidoc is not a view of a tracker query.

Artifacts can come from any tracker/project (permissions apply) but, in this first iteration, the helpers (to create new artifact in document) will be limited to only one tracker (see bellow "add section" for more details).

An artifact can be embedded in several documents, however a document can embed a given artifact only once.

Artidoc sections

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

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