Skip to end of banner
Go to start of banner

2022 LFN Workshop - Common Documentation and Tooling

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 10 Next »

Topic Leader(s)

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


Action Items:

  • Socialize Semantic commit messages with Projects and TAC – Require docs (Best practices need to be defined) to accept commits and releases 
  • Devise Templates for document types Scot Steele, Beth Cohen, Gergely Csatari
  • Document as you code Best Practice (Social contract) - WHO CAN TAKE THIS ONE?
  • Evangelist - Thomas Kulik?? Timo Perala??
  • 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 - WHO CAN TAKE THIS ONE?

  • 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
  • No labels