Hi, Thanks for the matrix and questions, Greg and thanks Michael and James for the following comments.
As a general response to Michael’s comments first, overall I think we need to clearly define a differentiation between the wiki and the release ONAP documentation. The wiki, by design, will be fluid and it is difficult to lock content to specific releases (in fact, what exactly will its purpose be once the first documentation had been released?). The documentation generated for each ONAP project should be created in some form of markup/markdown format and stored in the repository, built alongside the code and then output in a static format that is created per release version, as described in the documentation project: https://wiki.onap.org/display/DW/Documentation+Project To respond to Greg’s questions: Should we organize ourselves by topic, by project, or some other structure? I think by Project would probably be easiest to achieve. However, I don’t really know how the policing of content etc. is going to work. I suppose another option would be to have a “User Guide Editor” and an “API documentation guru”, etc. where an individual is responsible for one type of documentation and ensures consistency. I’m really not sure this is workable though. 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 See my reply above. I don’t know if this is really feasible. Will every topic have documentation updates driven by a scheduled release? If not how should we handle I would think that each release should have a minimum set of documentation requirements, as proposed by James. However, it could well be that some projects don’t need all the documents. I suppose we define the complete supported documentation list and the bare minimum list (Release Notes, Setup/Install, User Guide, API Reference, Developer, Trouble shooting). That list could perhaps be shorter… Matthew From: Michael O'Brien Sent: 21 June 2017 00:27 To: GLOVER, GREG L <[email protected]>; BENNETT, RICH <[email protected]>; HU, JUN NICOLAS <[email protected]>; [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: RE: ONAP Documentation scope 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]> [mailto:[email protected]] On Behalf Of GLOVER, GREG L Sent: Tuesday, June 20, 2017 16:36 To: BENNETT, RICH <[email protected]<mailto:[email protected]>>; HU, JUN NICOLAS <[email protected]<mailto:[email protected]>>; [email protected]<mailto:[email protected]>; GLOVER, GREG L <[email protected]<mailto:[email protected]>>; SCAGGS, KEVIN <[email protected]<mailto:[email protected]>>; WRIGHT, STEVEN A <[email protected]<mailto:[email protected]>>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]> Cc: [email protected]<mailto:[email protected]>; Shawn Loewen <[email protected]<mailto:[email protected]>>; Andrei Kojukhov <[email protected]<mailto:[email protected]>>; John Buja <[email protected]<mailto:[email protected]>>; Andrea Anderson <[email protected]<mailto:[email protected]>>; Matthew Harffy <[email protected]<mailto:[email protected]>>; Bernard Frazer <[email protected]<mailto:[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
