Topic Leader(s)
Topic Description
75m, Beth Cohen Scot Steele
Topic Overview
- Common documentation standardized guidelines – Minimum requirements and expectations, tools, types of documentation required for different types of projects.
- Common tooling – What is the current set of tools? Is there a possibility for consolidation? Is it needed? Is this even possible?
Slides & Recording
GMT20220315-151547_Recording_2560x1440.mp4
No slides
Minutes
Documentation is a necessary aspect of the technical project
Required for drive adoptability
No set standards on documentation within the community.
Different types dependent on project type
Doc types:
- Requirements docs (specifications, requirements),
- Code support (what the code does – sometimes in the form of user stories, release notes)
- User guides (how the artifact are used)
- Operations guides (how to support the artifact in production)
- Architecture guide (sample ways to architect a given system)
- Contributor guide (How a contributor can contribute to a project, beginner and advanced)
- Webpages, Wikis, Github, GitLab (repositories for project artifacts)
- Doc maps and threads (guides to help users to find docs that they need)
RST & Sphinx as tools, Some Docs are published by GSMA, Standard Repo OPNFV
What are current communities doing today:
Anuket: Reference materials are documentation, testing tools have some release notes and user stories, docs on how they are used. Minimal contributor guides , No ops or user guides yet.
Release announce
ONAP:
- Readthedocs- End user doc, release notes Still there is a big discussion in ONAP about moving the arch documentation wikis to rtd.
- Wiki - developer documentation, all non end user documents how to contribute, development notes
- Gergely Csatari In a sense that we store the docs in Git in different release branches and publish them to readthedocs, yes.
Storing them in the wiki makes it difficult to store release specific information in an organized way.
In git all documentation of one release sits in one branch. - ONAP wiki vs. RTD policy. - Just what doc types should live where: https://wiki.onap.org/x/jgLaB
5G Super Blueprint
- Build guides
- documenting POC shown in ONE summit
- Integration Guide
- Lessons learned
it's a much a historical doc
WaveLabs supported POC with Developer Interviews
Best Practice: Document as you code - ensures you have fresh info
How do we mimic what was done by previous people?
- Suggested BP - no release without Documentation
- Symantec commit messages?
- Topic oriented
- Automated Change logs
Suggestion - Templates that provide app
@Andrew Grimberg For those wondering what I mean by Semantic Commit messages from what I can find this seems to be the impetus behind it: https://gist.github.com/joshbuchea/6f47e86d2510bce28f8e7f42ae84c716 It's been more formalized here: https://www.conventionalcommits.org/en/v1.0.0/ I'll note that per the LF Release Engineering best practices we hold to seven rules of a great git commit message as espoused here: https://cbea.ms/git-commit/ so that means we actually enforce a capitalization of the subject line in our Se mantic commit messages as per rule 3 which differs from the above links. I'll further note that all of this linked from the LFRE's best practices documentation available here: https://docs.releng.linuxfoundation.org/en/latest/best-practices.html
Evangelist Team:
Action Items:
- Socialize Semantic commit messages with Projects and TAC – Require docs (Best practices need to be defined) to accept commits and releases - Evangelist team
- Devise Templates for document types (Best practices) Scot Steele, Beth Cohen, Gergely Csatari
- Best Docs Badge – Nominations for contributor who writes the best docs to make the code usable. Consult Brandon Wick ?
- Doc Maps - consider implementing as a Best Practice - Needs Volunteer
Wiffm / intrinsic values to provide to documenters (fun) and Rewards (impact on career) Scot Steele
- Kenny Paulto create the DocEvangelist list.
- Setup the first call - Scot Steele