6db19fcea2
This also updates Getting Started - CI/CD in your local dev - Linux & Mac doc.
A few other related doc changes were pulled in by this.
I wanted to try different versions of dagger on Linux, and this was the
easiest way of doing that:
curl -L https://dl.dagger.io/dagger/install.sh -O
# make this change, and then:
DAGGER_VERSION=0.2.0 sh install.sh
# ...
./bin/dagger version
dagger 0.2.0 (e499297e) linux/amd64
DAGGER_VERSION=0.2.1 sh install.sh
# ...
./bin/dagger version
dagger 0.2.1 (69b4845d) linux/amd64
This change enables anyone to do the following instead:
curl -L https://dl.dagger.io/dagger/install.sh \
| DAGGER_VERSION=0.2.0 sh
Until this gets merged, you can test how this change works in practice
via this temporary file:
curl -L https://dl.dagger.io/dagger/install-pr-1819.sh \
| DAGGER_VERSION=0.2.0 sh
One thing which I was not sure about is how the file from this
repository ends up on https://dl.dagger.io/dagger/install.sh. I think
this is a manual process today, but I need to confirm this assumption.
Signed-off-by: Gerhard Lazu <gerhard@lazu.co.uk>
FAQ
The intent behind this README is to answer contributor questions regarding docs.dagger.io.
What happens to a new doc page after the PR gets merged?
It gets automatically deployed to docs.dagger.io.
The doc URL will use the slug property from the doc markdown metadata.
Given slug: /1001/install/, the live URL will be docs.dagger.io/1001/install
How can I run docs locally?
You will need to have yarn and Node.js v16 installed.
From the top-level dir - cd ../ - run the following command: make web
This will install all dependencies, start the docs web server locally and open localhost:3000 in your browser.
How can I add a new doc page?
From the docs dir, run ./new.sh doc-title
This will create a new Markdown file for the new doc page, i.e. docs/1214-doc-title.md
This new doc will not be added to the navigation. We prefer to keep the organisation of doc pages, and writing them separate. For the time being - 2022 Q1 - the focus is on writing self-contained doc content. Don't worry about where to fit this content, it's enough to keep this in mind: Writing effective documentation.
What else should I keep in mind as I add new doc pages?
- "I would like the docs for http://dagger.io to be world-class… Any recommendations or advice?" - Solomon, Nov. 2021
- "I would propose starting off with common use case and get a feedback loop possible where customers get to somewhat steer the topics they want next. Maybe via a vote system to prioritise . The community leads it all." Frankie Onuonga via Twitter, Nov. 2021
- The Documentation System +1 from @samalba
- Maybe it’s time we re-think docs - Kathy Korevec, Jun. 2021
- 🎙 Ship It #17: Docs are not optional - Kathy Korevec, Aug. 2021
- 📚 Working Backwards - Colin Bryar & Bill Carr, Feb. 2021
- 🎬 LeadDevBerlin: Writing effective documentation - Beth Aitman, Dec. 2019
- 🎬 DocOps: engineering great documentation - Adam Butler, Dec. 2017
- 🎬 PyCon: Writing great documentation - Jacob Kaplan-Moss, Sep. 2014