2022 LFN Workshop - Common Documentation and Tooling
- Casey Cain
- Scot Steele
- Beth Cohen
Topic Leader(s)
@Scot Steele
@Beth Cohen
Topic Description
75m, @Beth Cohen @Scot Steele
Deep Dive on Interop Challenges
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
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:
@Gergely Csatari
@Beth Cohen
@Timo Perala
@Scot Steele
@Thomas Kulik
@Chaker Al-Hakim