refactor: improve writing and drop too implementation specific decisions

docs/decisions/0017-generalized-containers.rst

@@ -23,23 +23,25 @@ Decisions
 - Containers might be of different types, with each type potentially having different restrictions on the type of content it can hold but that will not be enforced by containers.
 - Content restrictions for containers are implemented at the app layer, allowing specific container types, like Unit, to limit their members to particular content types (e.g., only Components).
 - The course hierarchy Course > Section > Subsection > Unit will be implemented as relationships between containers, with each level acting as a container that holds other content. The hierarchy will be enforced by the content restrictions of each particular container but allowed to be overridden to support `0002-content-flexibility.rst`_.
-- Containers will follow extensibility principles in `0003-content-extensibility.rst`_ for creating new container types or subtypes, static or dynamic.
+- Containers will follow extensibility principles in `0003-content-extensibility.rst`_ for creating new container types or subtypes.
 
 3. Container Members and Relationships
 =======================================
 
 - The members of a container can be any type of publishable content.
-- A container holds references to generic data structures for defining parent-child relationships between a container and its members. These structures point to either static or dynamically generated content to allow associations for different types of content within the container.
-- Members are stored as a list of references to the content they hold to maintain ordering.
-- Each container holds different states of its members (e.g., user-defined state, initial state, last state) to support rollback operations.
-- Containers maintain a defined order for their members. When ordering needs to change, a new copy of the child should be created.
-- Each child can be fixed to a particular version or set to point to the latest version for draft and published states. Draft or published states can be referenced without creating new instances for each version update by using the convention of setting the reference to `None`.
-- If the child's draft or published version is pinned, then each time versions are updated, a new child with the new reference must be created.
-
-4. Container Versioning Management
+- Members within a container are maintained in a specific order as an ordered list.
+- Containers represent their content hierarchy through a structure that defines parent-child relationships between the container and its members.
+- The structure defining these relationships is anonymous, so it can only be referenced through the container.
+- Containers can hold both static and dynamically generated content, including user-specific variations.
+- Each container holds different states of its members (author-defined, initial, and frozen final state) to support rollback operations.
+- Containers support both fixed and version-agnostic references for members, allowing members to be pinned to a specific version or set to reference the latest draft or published state.
+- The latest draft or published states can be referenced by setting the version to ``None``, avoiding the need for new instances on each update.
+
+4. Version Control
 ==================================
 
-- The container itself is versioned, and a new version is created if and only if the container itself changes (e.g., title, ordering of contents, adding or removing content) and not when its content changes (e.g., a component in a Unit is updated with new text).
+- A new version is created if and only if the container itself changes (e.g., title, ordering of contents, adding or removing content) and not when its content changes (e.g., a component in a Unit is updated with new text).
+-
 
 5. Publishing
 =============