Suggestions for user-oriented documentation.

For potential users of DDI 4 we need a visual representation that is very simple and easy to grasp.

First and foremost I think we need to represent a hierarchy that will show users where they need to start when creating markup for a specific "View".
In DDI 2.1 we used a tree structure and that was intuitive and very useful. Even if that is no longer possible we still need to think about offering a view that will do a similar job.
Perhaps a diagram showing that DDI is the uppermost level, Study the next level. Under study we should group all of the elements that are enabled there, only displaying their name and enabling links from the name to individual element documentation. The elements should be represented with the actual element name as it appears in the xml instance.
Below this, another set of boxes grouping the elements that are necessary in order to complete a codebook but sit outside the study element in the xml.
For users we need instructions that are brief, simply stated, and concentrate on the kind of CONTENT that goes into each element, always carrying examples. None of the complicated technical details or references that we currently find in the classes' documentation.

I recently had to familiarize myself with a biomedical standard called ODM:

https://www.cdisc.org/standards/transport/odm

I was very impressed with the way their documentation was put together, as it helped me figure out the standard in record time. 
Of course ODM is far less complex than DDI, but perhaps we could attempt something similar for individual views.
They use a simple numbering system for indicating the hierarchies in the model, no diagrams. The numbering system makes it extremely easy to grasp the structure of the standard.  All fields in the list are linked to individual element documentation, which is laid out very briefly, and terms that are very easy to understand.  Also, this individual element documentation is not presented on separate pages, but on another page that lists all elements again, but this time described in detail. This is very useful because a user does not have to go back and forth to the original list, but can just scroll up and down the enhanced list.
Here is an example of an individual element documentation; it is a complex element, and yet everything is quite easy to understand.
3.1.4.1 SubjectData

Body:
 
	(AuditRecord?, Signature?, InvestigatorRef?, SiteRef?, Annotation*, StudyEventData*) 	 
Attributes:
 
	SubjectKey 	subjectKey 			   
	TransactionType 	(Insert | Update | Remove | Upsert | Context) 	(optional) 	The TransactionType attribute need not be present in a Snapshot document. 	 
Contained in:
 
	ClinicalData 	 
Clinical data for a single subject. 
The SubjectKey is used to name a specific subject. This key is unique within the parent study. If a subject has data for two or more metadata versions, the subject key must be the same in each. 
Example: 
<ClinicalData StudyOID="P2006-101" MetadataVersionOID="101.01">
   <SubjectData SubjectKey="1000" TransactionType="Insert">
      <StudyEventData StudyEventOID="101.Screen">
         <FormData FormOID="101.DEMOG">
            <ItemGroupData ItemGroupOID="101.DM">
                <ItemDataString ItemOID="101.USUBJID">101-001-001</ItemDataString>
                <ItemDataString ItemOID="101.SEX">F</ItemDataString>
            </ItemGroupData>
        </FormData>
        <FormData FormOID="101.LABDATA">
            <ItemGroupData ItemGroupOID="LB.101">
                <ItemDataDateTime ItemOID="101.LBDTC">2006-07-14T14:48</ItemDataDate>
                <ItemDataString ItemOID="101.LBTESTCD">ALT</ItemDataString>
                <ItemDataString ItemOID="101.LBORRES">245</ItemDataString>
            </ItemGroupData>
        </FormData>
      </StudyEventData>
  </SubjectData>
</ClinicalData>
<ClinicalData StudyOID="P2006-101" MetadataVersionOID="101.02">
  <SubjectData SubjectKey="1000" TransactionType="Insert">
      <StudyEventData>
        <FormData FormOID="101.AENONSER">
            <ItemGroupData ItemGroupOID="AE.101">
                <ItemDataString ItemOID="101.AETERM">Fever</ItemDataString>
                <ItemDataDate ItemOID="101.AESTDTC">2006-08-21</ItemDataDate>
            </ItemGroupData>
        </FormData>
        <FormData FormOID="101.LABDATA">
            <ItemGroupData ItemGroupOID="LB.101">
                <ItemDataDateTime ItemOID="101.LBDTC">2006-07-14T14:48</ItemDataDateTime>
                <ItemDataString ItemOID="101.LBTESTCD">ALT</ItemDataString>
                <ItemDataString ItemOID="101.LBORRES">300</ItemDataString>
            </ItemGroupData>
        </FormData>
      </StudyEventData>
  </SubjectData>
</ClinicalData>