Artidoc Structure covers the following elements:
having titles to organize sections (1. Introduction > 1.1 Context, etc)
having zones of "free" text. Free text is a text that is not part of the tracker associated to an Artidoc. For instance, given an Artidoc associated to a Requirement tracker, a new free text section will not generate a new Requirement artifact.
Persistence of Structure
There was a lot of thoughts on how to store Structure elements. There was two options: either store them as special artifacts or dedicated objects. We decided for "Dedicated objects", see bellow for the arguments. The arguments of Artifacts can be found in followup comments of this epic.
Dedicated objects
Artidoc Structure sections would be backed as dedicated objects, at artidoc level
Good, because it's simple, we don't need to worry about Artifact side effects
Good, because as it's simple, the implementation should be faster for initial use case
Good, because it doesn't add more pressure to Artifact* tables (in term of volume)
Bad, because there is a need for a specific management of images (including TUS upload)
Bad, because we will have to implement specific features for
Bad, because we will have to implement history from day 1 (including images)
Bad, because it cannot be extended to manage "fields" (but maybe we can convert them to artifacts, or have explicit Requirement Artifacts for that)
Bad, because we might need to manage comments with two different approaches if we decide to store artidoc comments as Artifact Follow-up comments (but that might not be a good idea after all).
Free text
Free text is a section (Title + Description) that is not backed by an artifact. It's possible to have Free Text without description (pure title), Free Text with both Title and Description but it's not possible to have Free Text without title.
Free text section offers the same formatting possibilities than artifact sections, including images and Subtitles
When an Artidoc is duplicated, the free text sections are duplicated too.
It's possible to create Free Text sections in an empty document.
When author remove a Free Text from a document, they should confirm removal (it's not possible to re-add afterward unlike artifacts).
Introduction of free text have an impact on the management of document versions (see dedicated section after).
Management of titles
The management of titles is a challenge in itself. With the original (16.0) approach we have two levels of titles to manage:
One that is given by the artifact (and with the introduction of Structure, of artifacts)
One that is inside the paragraph of the section (description)
With the introduction of Structure, we will have two series of titles to manage. The titles given by the Structure (1. Introduction, 1.1 Context) and the titles inside paragraphs.
This might not be too much of an issue for Requirement Sections because it's a special type of Sections. But for Structure, it will be unbearable for end users. They will be proposed to create a new Structure. This Structure could be just a Title, just a Text or both. If they choose to text, they can select a Title inside the paragraph but this title won't be taken into account in the outline 🤯.
Structure have 3 level of titles
Structure provides 3 levels of title (Heading 1, heading 2 and heading 3). While technically we can go up to 6 levels of titles, it's quite hard to make visual differences between levels after level 3. Plus it seems to be a good practice to limit the number of levels to reduce the complexity of documents. Finally, if a compelling need to have more than 3 levels of titles arise, we can add a new one whereas removing a level if it generates too much of complexity is way more complex.
Structure titles are the only one that appears in the Table of Contents.
Descriptions have one level of title
Descriptions (of artifacts or free text) only propose one level of title that is called Subtitle. Subtitles doesn't appears in the table of contents and cannot be linked.
The goal is to let users organize their descriptions with a meaningful tag (subtitle vs using bold to fake a title) while limiting the risk of misunderstanding between Headings and and Subtitles.
Note: existing artifacts that use more than one level of title in their description are rendered with an appropriate font size. It's however not possible to use the other description titles size (h2 and h3) in Artidoc.
Scenario of title usage
Limitation of headings
Example:
1. Requirements
2. <h1>Radiation [-> cannot move]
2.1 <h2>Advanced spacecraft [-> can move to h1]
2.1.1 <h3>Life support [-> can move to h1, h2]
Radiation title cannot be changed because there is already an h2 and h3 below
Advanced spacecraft can move to h1 but not h2 because there is a h3 below
Life support can move to h1 or h2
Reorder section doesn't change the depth of titles/sections
1. Requirements
2. Radiation
2.1 Advanced spacecraft
2.1.1 Life support [move bottom]
3. Random stuff
Becomes
1. Requirements
2. Radiation
2.1 Advanced spacecraft
3. Random stuff
3.1.1 Life support [move top]
Becomes
1.1.1 Life support
2. Requirements
3. Radiation [move top]
3.1 Advanced spacecraft
4. Random stuff
Becomes
1. Radiation
1.1.1 Life support [move down]
2. Requirements
2.1 Advanced spacecraft
3. Random stuff
Becomes
1. Radiation
2. Requirements
2.1.1 Life support
2.2 Advanced spacecraft
4. Random stuff
User can create incoherent levels of titles
1. Requirements
2. Radiation
3. Advanced spacecraft
4. Random stuff -> move h3
Becomes
1. Requirements
2. Radiation
3. Advanced spacecraft
3.1.1. Random stuff