Packages node UI spec - underspecified and hard to read

Hello, group,

I have worked with Java Projects UI spec (rev. 1.24) to adapt code that
implements Packages node. Below you will find a list of issues found in
the UI spec; some of them are functional, some of them are formal
(objections to document readability and/or usability as a reference).

------------------------------------------------------------------------
Functional issues:

The spec briefly says that a package structure is collapsed
if the intermediate package levels contain no data.

The UI spec does not actually specify the collapsing behaviour - it only
gives a few examples of how it would appear in selected situation, but
no logic to implement.

In the situation, that the collapse actually happens, these
behaviours are not specified:

* Collapsing - where it happens ?
Does it happen only from at the level of direct children of
the Packages node ? Anywhere in the structure, where there are
several empty levels ? Coalesce infinite number of levels (up to
the first non-empty), or some limited number of levels ?

* Dynamic behaviour of collapsing
If last data item in a level is deleted, should the structure collapse
into a single node ?
If a data item appears, such as result of some tool operation or
external operation, should be the structure expanded ?

The following standard operations are not covered at all by the UI spec:

* Rename, Delete, Copy, Cut: these actions is not present in the
[individual] Package node's action list. Will they not be there ?

* Rename: What the user should see in "Rename" dialog ?
Full package's name or just the last component ? If the former,
how exactly will the rename operation proceed, if the user
changes names of more components of the full package's name,
enters fewers components or more components ?

* What will "delete" operation on the node do ? Delete everything from
the topmost folder(s) collapsed into the node ? Delete only folders
that correspond to the last component ? Different "delete" action UI ? How
it should look ?
What should be done when the node is destroyed programmatically (abstract
delete action for the node) ?

* How exactly will Paste action work on the collapsed node ? Paste into
folder that correspond to the last collapsed component ? Give the user a
choice when there's more matching folders ? Offer a choice to paste to
any level of the collapsed structure ?

* What will "Copy" and "Cut" operations do on a collapsed structure:
- entire structure from the topmost folder(s) will be copied
- only the lowest level will be copied
- how to handle multiple merged folders ?

-------------------------------------------------------------------------
Now the second point - readability of the document:
The document tries to retain a formal structure, but IMHO either the
structure is not designed to be used as a reference for implementors or
reviewers, or the document fails to fill the structure properly.
The result is that it is hard to read it and precisely follow it when
information are scattered around, rather than connected together (or
hyperlinked between). The specification seems also quite imprecise when
it comes to details. Here are some examples:

* Specifications for different nodes are mixed together:
See paragraphs after "Sources node". Pieces of specs for different
nodes, namely "Sources node", "Source" node, "Folders and Files",
"Folders" and "All nodes".

The sections are illogically sorted by type of UI (props, customizer,
actions), rather than the node, or place of appearance as the rest of
document is; when reading the spec or implementing it, it is rather
dificult to navigate that way.

The same - and even worse you can find after "Packages node Customizer".

* Using undefined terms.
"Source node" is not defined; I assume that it stands for a node which
represents a [generic, non-java] source root. But the spec for Sources
node fails to say when they appear, when they disappear, and how they
are connected with the java-specific portion. If they are not, why they
are mentioned in the spec ?

* Balast information
"Properties - Folders and Files
Not Specified"
I wonder what information this brings to the reader.

* Please do no use paragraph numbers as anchors. It is *extremely* hard
to link into the document and maintain those links, especially when
numbering may change from time to time.

* Absolute URLs should not be used, if there's other way to reference
the place. Keep in mind that offline browsing should be supported for
reference documentation.

* Rather imprecise specifications
"Actions - Folders: Add as Java Root - ...".
Sure it is not present on all folders, right ? It is only on folders, which:
- are not itself inside any java root
- are not itself a parent of an existing java root
[for less careful readers: you can not correctly define a java root
inside another or above another, since one of them would then work with
incorrect paths to resources in the shared portion]

Imprecise position qualification, or description of behaviour can be
found in other areas, too.

And finally a really minor thing:
* Packages node spec and the following subsections are not linked from
document contents (very minor, but the section "Managing sources" is
quite large)

-----------------------------------------------------------------------

Note that the following issue were extracted strictly from the section
"Managing Sources". I would not dare to extrapolate to the entire UI
spec document.
As a summary I am slightly wonder how it is possible to have the main UI
document in such state after a half-man-year of work: poor readability
and structure, imprecise formulations or whole behaviours unspecified or
underspecified.

Can someone from HIE team answer the question and - much much
importantly - fix the issues ?

Thank you,
-Svata