Topic Leader(s)
Topic Overview
Documentation is a key topic in the various LFN projects. We propose this unconference to discuss what are possible synergy among LFN projects to share best practices and painpoints, ease documentation maintenance and migrations from wiki. Introduction to other sessions: ONAP documentation starter kit and ODL Opendaylight documentation talk
Slides & Recording
Minutes
- 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
- We made a TSC decision on this, did we not?
- 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:
- In Policy the practice is that a Jira cannot be closed without documentation (https://wiki.onap.org/display/DW/Policy+Project+Team+Developer+Contribution+Requirements)!!
- → maybe a good practice for ONAP ?
- 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 difficulties Eric Debeau Guillaume Lambert Andreas Geissler
- Share jjb best practices (Guillaume Lambert(ODL) just submited a patch on ONAP/OOM project to include spelling check (inspired by 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