Versions Compared

Version Old Version 8 New Version Current
Changes made by

Morgan Richomme

Eric Debeau

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  • 37 participants
  • Opening and presentation (see slides) - Eric+Guillaume
    • Documentation purposes (Main- and Subproject Documentation)
    • How to attract new contributers ? (too few, complex journey)
    • Wiki vs. RTD/MD
      • Wiki → Project documents, minutes,... no review, no release alignment,..
      • RTD → like code, review process, more difficult for nod-developers
    • Some challenges
      • Avoid Wiki for official Documentation
      • more automation required (code quality, linting, spell checkers...)
      • More reviews (e.g. from native speakers)
      • No Doc → No Release ?
  • Gergely:
    • What is "Project Documentation" and how it is organized ?
    • Guillaume: 
      • All Product documents should be stored as RST files in Gerrit/Git
      • All Project documents should be in Wiki
  • Catherine: 
    • should not the documentation be hosted where any user, developer will look first concerning a particular release? Release note ?
    • it would be interested what other LF open source communities are doing?
    • Maybe get a TAC recommendation?
  • Cedric:
    • We are writing far too much in Wiki.
    • Wiki should be a first step referring the doc in tree.
    • And we are mixing wiki and project management.
    • I like the fact that the release notes are currently in tree.
    • Guillaume:
      • Right, Cédric, - that's exactly the point - too many things are on the wiki and should be on the official documentation in a more maintainable format
  • Morgan:
    • people jumping to other projects never clean their wiki pages, pages are never deprecated..
    • that is why we got lots of misleading pages in wiki because no one feel really responsible for the pages.
    • The PTL are responsible for the consistency of the official documentation that is versioned,
    • it is impossible to have the full view on a wiki, which is fully open by definition.
  • Ciarain:
    • We made a TSC decision on this, did we not?
      https://lists.onap.org/g/onap-tsc-vote/topic/71405726#1381
    • Andreas:
      • yes, we have an agreement, but still not all content is migrated to RTD
      • And still many things are still only in Wiki (e.g. Architecture is only partly in RTD - Eric works on it...)
    • Catherine
      • Ciaran, you are right but this topic today is not only about ONAP
    • Yes, sorry Catherine - just trying to show some prior art on a proposal for a potential split between wiki and under source control
  • Gergerly:
    • Is it possible to return errors in linting, when links to Wiki are created in RTD ?
    • Sylvain:
      • Only checks for working links included.
    • Morgan:
      • Links to Wiki not always avoidable.
  • Eric:
    • Documentation strategy accepted in other communities (e.g. CNCF) ?
    • Gregerly:
      • CNCF moved RTD, which is accepted, and you can use previews,...
      • and release versioning is supported in RTD
      • ONAP → problem 
        • it is not in the definition of done (document while coding)
    • Ram Krishna:
  • Eric:
    • How to attract new contributors ?
    • Gregerly:
      • Have a good guide and instructions for newcomers
    • Cedric:
      • RST is a bit more difficult than MD, but should not be a problem for developers
    • Morgan:
      • contribution with gerrit/git opens way to other projects,...
      • Documentation should be a "must have" for contributors
      • We need to help the people (e.g. best practice, work with gerrit,...)
    • Ranny:
      • sometimes contributers are only part-time workers and the barrier should be lowered for them
    • Cedric:
      • Developer can help the temporary worker to checkin code
    • Eric:
      • We need to train the people to contribute....
      • maybe LFN can help
    • Sylvain:
      • Gerrit is more difficult than Gitlab/Github, especially to do minor modifications. MD is also directly visible in GitLab/Github.
      • Simpler workflows needed for the future
    • Cedric:
      • Gitlab is nice, but when handling dependencies is better in Gerrit, especially in big projects
    • Robert:
      • Workflows in all solution are similar, but different. Effort to port Github/Gitlab contributions back to Gerrit might be possible.
    • Andreas:
      • We need a project specific booklet for new comers that allows easily potential contributors to publish or modify their documentation.

Discussions/

...

Proposals

Action Items

  •  Ask 2-3 members of project X to give a try to the "get started" guide of project Y (no beginners) - 1-2 days to see if the doc is easy to find/follow, report

...

...

  • OpenStack gates)

...

  •  Ask LF to create a xproject portals/set of

...

  • video 
    • My first patch from a windows/mac:Linux desktop (beginner)
    • Support (mailing list/slack/..)
    • The official documentation entry points

...

  •  Share best-practise in ONAP community to only close JIRA tickets when documentation produced Ram Krishna Verma