Guidelines / Best Practices

  • Please follow the DeveloperWiki and ReadTheDocs Usage Policy
  • Pick good page title names representative of page content, unique across wiki space, and that won’t change in title but could be moved around in the page tree hierarchy. 
  • Avoid changing page titles, but if you expect changes will be needed, use the tiny URL link when referencing in email, external to wiki space site references, etc.
  • Avoid splitting up page content once it has been published and comments/references exist.  Context assumptions are subtle and easily broken.
  • Consider using page tree hierarchy and/ or label query macros to organized multiples pages are expected to be added under a higher level page rather than maintaining a list of references in the higher level page content.
  • Embedded images sometimes will pixelate - reedit the size by a couple pixels on a 2nd save and they should be fixed.
  • Notice that any 2nd level pages will appear in the landing page - if you place any new page at level 3 or below - it will keep the landing page concise.
  • Recording your screen: OSX will record your screen if you have the QuickTime Player installed - see the ONAP 1.0 Demo videos as an example.


4 Comments

  1. Michael O'Brien

    In response to

    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).

    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 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.

    2)      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 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 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


    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 -  DOC-7 - Getting issue details... STATUS

    Wiki - 

    /michael

  2. Matthew Harffy

    Responding to: https://lists.onap.org/pipermail/onap-discuss/2017-June/001855.html

    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

  3. Michael O'Brien

    Gliffy from the "+" menu during editing is an excellent "edit in-line" method of keeping modifiable diagrams in our confluence - thanks Roger.

    see example at Overall Deployment Architecture

    /michael

  4. DeWayne Filppi

    It would be useful to be able to delete pages.