Formatting needs

For a great technical writing experience there are a couple of things that needs to be considered:

• Support of Tables
• Support of preformatted text and inline code
• Support of emojis
• Support of Graphs

Structure needs

Documents often need to be structured in a composable fashion (parent/child relationship). When an artifact that have children is in an Artidoc, the children should be displayed hierarchically. 

Example, given the following Artifact structure:

• (Epic 123) Revolutionize Patient Monitoring with AI-Enhanced Wearables
  • (Story 555) Seamless Integration with Existing Systems
  • (Story 556) Real-Time Alert Notifications
• (Epic 124) Streamline Surgical Procedures with Smart Instrumentation
  • (Story 557) Automated Instrument Tracking
  • (Story 558) Precision Guidance for Surgeons

The corresponding Artidoc would be:

• 1. Revolutionize Patient Monitoring with AI-Enhanced Wearables
  • 1.1 Seamless Integration with Existing Systems
  • 1.2 Real-Time Alert Notifications
• 2. Streamline Surgical Procedures with Smart Instrumentation
  • 2.1 Automated Instrument Tracking
  • 2.2 Precision Guidance for Surgeons

To be refined: how to we handle the recursive structure of the tree ?

There is a wish/dream from users to have the full structure available but that comes with some questions:

• Do we really want the whole sub-structure ? Like including tasks bellow the user stories ?
  • Is that per document ? per view ? per viewer ?
• How do we manage the potentially very large documents that would be generated ?
  • Is there any form of expand/collapse approach ?
  • Should it be all expanded ?

An approach that could simplify the reasoning is to consider that children are explicitly added to the doc. If we make a parallel with actual “Pure Documents” (aka Word files) the document is only as big as writer (and text processor software) can handle/write. There is little to no reasons that one would start adding tasks into a document. So Writer would add “Epics” and “User Stories” and as long as they are added to the document, they are displayed.

That could work when Artidoc are only created/update with the Artidoc interface. But what should we do if someone goes directly to the artifact to add a new children ?

• Do not automatically add the child to the artidoc (artidocs actually)
  • Pro: there is no risk to get fat documents with unwanted contents (tasks in high level requirements)
  • Cons: when a legit child is added with another mean than artidoc, it must be added explicitly to artidoc (artidocs actually). Maybe there is a need for a tool to check for consistency ?
  • Cons: we need to store at Artidoc level whether a child should be rendered (on the other side, we are likely to store it anyway as we will have to deal with the ranking)