just for reference

https://lists.onap.org/pipermail/onap-discuss/2017-June/001704.html

Greg,

    Thanks for the matrix, and good questions.  I have a couple minor observations that may help with the discussions (while working through ONAP for the past 6 weeks).

• Coverage: Releases:
  Some of the content is still 1.x (pre upcoming R1 (as in new approved projects from June – the old https://wiki.onap.org/display/DW/Proposing+A+Project in the new https://wiki.onap.org/display/DW/ONAP+Projects )) – for example the architecture section may need to be expanded/refactored to include the new projects post 1.1.0 – in view of this we may want to partition parts of the wiki or at the page-level into 1.x (major difference between 1.0.0 and 1.1.0 is an additional AAI instance) and R1. This would depend on how much we are planning on supporting past versions like 1.0.0 and 1.1.0 or make the wiki R1 centric – likely recommended.

From my perspective the wiki currently serves 3 views of ONAP (1.0, 1.1 and the upcoming R1)

I also think that multiple views of the system are good – so there will varying levels of coverage.  For example the demo pages and the design pages each detail at different levels for design and deployment – interleaved they form a more complete view.  The development setup pages also complement/overlap with the development guides.

• Organization:
  I understand that the first 2 levels of the tree are actively managed to keep the landing page concise – so non-documentation members usually don’t add pages until level 3. Therefore the 3^rd^ level and below are open to creating new sub-pages to differentiate content by anyone.  That said though since the wiki is a living/just-in-time-delivery set of pages – they are under constant editing to keep the content accurate/relevant by most of us. 
• Responsibility:
  Developers/architects/essentially all overly enthusiastic committers/contributors will edit content as they selectively target/run/debug/integrate/reverse-engineer/understand/validate individual components and the E2E system. I think it is essential that as much discussion happens on the wiki as possible so that the all of us can participate and view issues/discussions after the fact – therefore the wiki needs to be as accurate as possible and in sync with the repos.
  Historical content on the wiki – in its history/questions/discussion is essential when one needs to dive into a particular component – (it solves some of the “don’t know what we don’t know”)

• Artifacts: (code/wiki/jira/newsgroups/questions)
  The wiki is one major part of the documentation set – in my opinion the 2^nd^ most relevant (after the code – which it should match) in defining the “actual” system – this includes history and searchable discussion in the questions at the bottom of the page (which contains a valuable subset of each page KB).
  There is also the questions section on the wiki – where the content is close to/complements the comments on relevant pages.
  And the archives of the soon to be 5 news groups.
  And the Epics/Stories/Subtasks in JIRA – we can make jira-wiki bidirectional links as much as possible.

And the code comments (both in Javadoc and non-javadoc comments) – there is a lot of history there.

The GUI content indirectly drives part of the WIKI documentation via posted screen captures.

The demo flows are particularly important – as they are our view of ONAP presented to potential users/customers of ONAP.

The overall REST API (a combined northbound OSS set for full automation of ONAP) is a sort of machine readable documentation of ONAP – especially if we export live/generated Swagger docs (therefore the example JSON content is a form of documentation)

And finally the generated Javadoc html content from the code

• Missing?:

1. I would like to see a section for design issues – where we could link JIRAs to – which would list design/analysis discussions/decisions before submissions – these could be used to understand an existing system’s direction decision and use during code reviews. However a discussion should be done on where we wish to document design content “during” development
2. Diagrams: there is a separate discussion on tools – currently we post png files and try to keep them updated for things like flow/structure diagrams – plantuml can be used more for some of this.
3. There are a lot of word/excel/ppt attachments to the wiki (some of them on swagger API docs) – I recommend we try to put these artifacts as editable tables where possible in the wiki

Thank you

/michael