Open sourcing your repository:

 

a roadmap

 

a personal journey

 

 

Intent: help you move to open source

 

URLs

@theMikeJang

Slides: https://slides.com/mike-1/open-source-and-docs

Blog: https://ai-techwriter.com

Repo: https://github.com/nginx/documentation

Open source notes

@theMikeJang

Presentation built on slides.com

Framework: reveal.js

Blog: https://ai-techwriter.com

Open source does not exclude private discussions

We still have internal documentation repositories

Technical Writer

  • Author (RHCE)

  • Linux Annoyances for Geeks

  • Linux user since 1999

  • Principal Technical Writer, NGINX (F5)

    • I've always tried to contribute

CC0

@theMikeJang

https://slides.com/mike-1/open-source-and-docs

Background

@TheMikeJang

 

Earned a living from OSS

 

I've open sourced a doc repo before

It's easier if you're 'starting from scratch'

Lesson: Lawyers in tech know OSS

docs.cobalt.io

Result: Creative Commons license

Last year

@TheMikeJang

Fossy.us talk: You've been laid off. Now what?

Key tool: portfolio in a Git repo

Quickie demo: make that repo public

https://gitlab.com/mjang-test-group/mike_jang_qualifications

Audience

  • Writers
  • Developers
  • PMs
  • Testers
  • Others

@TheMikeJang

Pixabay CC0

https://www.f5.com/products/nginx

Disclaimer

The view expressed on this web site/blog are mine and do not necessarily reflect the views of my employer

Question

Is anyone 100% open source

Minimum: protect PII, security

Others: protect customer info

Others: protect new features until they're "ready"

NGINX and Open Source

 

NGINX Open Source = 280,049

all other NGINX ~170,000

 

 

What? NGINX docs were not open source?

 

 

This time last year, I looked for help

 

Steps to open source

  1. Management support
  2. Open source strategy
  3. Security and Compliance
  4. The "right" license
  5. Prepare for Contributors
  6. The transition

Steps to open source

  1. Management support
  2. Docs and open source
  3. Security and compliance
  4. The "right" license
  5. Prepare for contributors
  6. The transition

Management support

When is it "right" for the business

Our docs serve mostly OSS

Time period = quarter (3 months)

Unique visitors
 

NGINX (OSS) ~ 280,000

Other NGINX software ~ 170,000

Open source and business objectives

  • Market leader

  • Easier to work with customers

  • Help from the community

  • Talent pipeline

Open source and the community

  • Transactional

  • Here's what you get for contributing

  • The features you want

  • Portfolio building

  • Customers get what they want

  • Potential new job

Value of Open Source

Frank Nagle, Chief Economist, Linux Foundation

Steps to open source

  1. Management support
  2. Docs and open source
  3. Security and compliance
  4. The "right" license
  5. Prepare for contributors
  6. The transition

Docs

Essential to open source

 

Help with onboarding

 

 

Enhances customer retention

 

One year ago

Docs repo was closed

Corporate committment to open source

Template repository

Docs repo was closed

Corporate committment to open source

 

Pick the (OSS) license of your choice

 

Template repository

github.com/nginx/template-repository

Code of Conduct

Source: ContributorCovenant.org

Contributing Guidelines

Modified from our template repository

Steps to open source

  1. Management support
  2. Docs and open source
  3. Security and Compliance
  4. The "right" license
  5. Prepare for Contributors
  6. The transition

Challenges

Personally identifying information

Docs-as-code

Review standards

Personally Identifying Information

Usernames, passwords

Unique domains - RFC 2606

Unique IDs 

Auth tokens

Docs-as-code

Markdown with an SSG

Build tools (`make`)

Plugins

May require security evaluation

Review standards (PR/MR)

Code samples

PII

Links

Steps to open source

  1. Management support
  2. Docs and open source
  3. Security and Compliance
  4. The "right" license
  5. Prepare for Contributors
  6. The transition

Stakeholders

Lawyer

Engineering manager

Community lead

License options

Creative Commons

GPL FDL 1.3

Apache 2.0

BSD 2 

 

IANAL

 

BSD 2

Contributor license agreement

Protect the open source in your software

https://github.com/f5/f5-cla

IANAL

Steps to open source

  1. Management support
  2. Docs and open source
  3. Security and Compliance
  4. The "right" license
  5. Prepare for Contributors
  6. The transition

Contribution guide

Include the community in the SDLC

Show them how to  build your software

Include the community in the SDLC

Templates for issues, PRs/MRs 

Contributor license agreement

The community and the SDLC

Issues, PRs, MRs, Sprints

Excellent contributors may not know the SDLC

Software development life cycle

Template: Issues and PRs/MRs

https://github.com/nginx/documentation/tree/main/.github/ISSUE_TEMPLATE

How to build your software

Prerequisites (e.g. python, node)

Demo

Build commands. Makefiles.

Good first issue

Minimal knowledge of software

Documentation: "gateway drug"

Software - Quick win issues

Docs - Good first issues

Steps to open source

  1. Management support
  2. Docs and open source
  3. Security and Compliance
  4. The "right" license
  5. Prepare for Contributors
  6.  The transition 

Protect private commits

Use existing content

Mask commit history

Protect PII, customer info

Process

Rewrite commit history

https://github.com/newren/git-filter-repo

Archive old repository

Create new repo, existing content/commits

Rewrite commit history

Question

Is anyone 100% open source

Minimum: protect PII, security

Others: protect customer info

Others: protect new features until they're "ready"

Protect internal development

Competitive features

Customer-specific

Internal discussions

Internal mirror repository

Steps to open source

  1. Management support
  2. Docs and open source
  3. Security and Compliance
  4. The "right" license
  5. Prepare for Contributors
  6.  The transition 

Lessons Learned

Steps to open source

  1. Management support
  2. Docs and open source
  3. Security and Compliance
  4. The "right" license
  5. Prepare for Contributors
  6.  The transition 

Lessons Learned

Steps to open source

  1. Management support
  2. Docs and open source
  3. Security and Compliance
  4. The "right" license
  5. Prepare for Contributors
  6.  The transition 

Lessons Learned

 

Template:    https://github.com/nginx/template-repository/

 

Steps to open source

  1. Management support
  2. Docs and open source
  3. Security and Compliance
  4. The "right" license
  5. Prepare for Contributors
  6.  The transition 

Lessons Learned

 

  • Remove PII
  • Audit docs-as-code software
  • Set standards for reviews

 

Steps to open source

  1. Management support
  2. Docs and open source
  3. Security and Compliance
  4. The "right" license
  5. Prepare for Contributors
  6.  The transition 

Lessons Learned

 

  • Creative Commons 4.0
  • GNU FDL 1.3
  • Apache 2.0
  • BSD 2.0

 

IANAL

 

Steps to open source

  1. Management support
  2. Docs and open source
  3. Security and Compliance
  4. The "right" license
  5. Prepare for Contributors
  6.  The transition 

Lessons Learned

 

  • Contribution guide 
  • Good first issues
  • "Quick wins"

Steps to open source

  1. Management support
  2. Docs and open source
  3. Security and Compliance
  4. The "right" license
  5. Prepare for Contributors
  6.  The transition 

Lessons Learned

 

  • Old commits: keep private
  • Use a mirror internal repo

 

Open sourcing my portfolio

Merge request: https://gitlab.com/mjang-test-group/mike_jang_qualifications/-/merge_requests/1

URLs

This talk:    https://slides.com/mike-1/open-source-and-docs/

Doc repo:    https://github.com/nginx/documentation/

Contributor License:    https://github.com/f5/f5-cla/

Contributor Covenant:    https://www.contributor-covenant.org/

Template:    https://github.com/nginx/template-repository/

Quick wins: https://gitlab.com/groups/gitlab-org/-/issues/?label_name=quick%20win 

Rewrite commits:    https://github.com/newren/git-filter-repo 

My portfolio:    https://gitlab.com/mjang-test-group/mike_jang_qualifications

Request

NGINX

Community Survey

 

Expires Sunday August 3 -- 5pm

 

Questions

 LinkedIn: https://www.linkedin.com/in/mijang/

Open Source and Docs

By Mike

Open Source and Docs

  • 84

More from Mike

  • UI Text: The prequel
    Mike
    33
  • You've been laid off. Now what?
    Mike
    609
  • Helping AI hallucinate: it's a whole new language!
    Mike
    597
  • When Linux on the Desktop (2023)
    Mike
    487