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).
1) 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<https://wiki.onap.org/display/DW/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<https://wiki.onap.org/display/DW/Installing+and+Running+the+ONAP+Demos>
and the design pages<https://wiki.onap.org/display/DW/Design> each detail at
different levels for design and deployment - interleaved they form a more
complete view. The development
setup<https://wiki.onap.org/display/DW/Setting+Up+Your+Development+Environment>
pages also complement/overlap with the development
guides<https://wiki.onap.org/display/DW/Development+Guides>.
2) Organization:
I understand that the first 2 levels of the tree are actively managed to keep
the landing page<https://wiki.onap.org/display/DW/Developer+Wiki> concise - so
non-documentation members usually don't add pages until level 3. Therefore the
3rd 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.
3) 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")
4) Artifacts: (code/wiki/jira/newsgroups/questions)
The wiki is one major part of the documentation set - in my opinion the 2nd
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<https://wiki.onap.org/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<https://wiki.onap.org/display/DW/Mailing+Lists>.
And the Epics/Stories/Subtasks in
JIRA<https://jira.onap.org/projects/DOC/issues/DOC-6?filter=allopenissues> - 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
5) Missing?:
a) 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
b) 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.
c) 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
Links:
This newsgroup -
https://lists.onap.org/pipermail/onap-discuss/2017-June/001704.html
Jira - https://jira.onap.org/browse/DOC-7
Confluence - Q on https://wiki.onap.org/display/DW/How+to+Contribute+to+the+Wiki
Thank you
/michael
From: [email protected]
[mailto:[email protected]] On Behalf Of GLOVER, GREG L
Sent: Tuesday, June 20, 2017 16:36
To: BENNETT, RICH <[email protected]>; HU, JUN NICOLAS <[email protected]>;
[email protected]; GLOVER, GREG L <[email protected]>; SCAGGS, KEVIN
<[email protected]>; WRIGHT, STEVEN A <[email protected]>; [email protected];
[email protected]; [email protected]; [email protected]
Cc: [email protected]; Shawn Loewen <[email protected]>; Andrei
Kojukhov <[email protected]>; John Buja <[email protected]>; Andrea
Anderson <[email protected]>; Matthew Harffy <[email protected]>;
Bernard Frazer <[email protected]>
Subject: [onap-discuss] ONAP Documentation scope
All,
Attached is a first cut at mapping the ONAP topics (Developer wiki) to the 24
approved projects. Note the following:
* The topics are listed down the side and are separated into three tabs:
Technical, Project Mgt and Community
* The projects are listed across the top (project descriptions are in the
row below)
* The topics and projects are highlighted in red if they have at least one
intersection ("X"). Note there are a few of each that aren't highlighted.
Some questions we'll need to answer:
? Should we organize ourselves by topic, by project, or some other structure?
? Is our team responsible for overseeing every topic (insuring documentation
is accurate, timely and comprehensive)? I would think for Technical topics
absolutely yes, but what about Project Mgt and Community topics
? Will every topic have documentation updates driven by a scheduled release?
If not how should we handle
? Are there topics and/or projects that are missing? I didn't include the
list of proposed projects - they may help fill in some gaps
This message and the information contained herein is proprietary and
confidential and subject to the Amdocs policy statement,
you may review at https://www.amdocs.com/about/email-disclaimer
<https://www.amdocs.com/about/email-disclaimer>
_______________________________________________
onap-discuss mailing list
[email protected]
https://lists.onap.org/mailman/listinfo/onap-discuss
