diff --git a/README.md b/README.md index 3ea6542ded..b43128d10f 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ An even more fragile process that needs documenting and fixing. Note specificall WIP (Work In Progress) Docs on how to do this: -1. In `_data/..speakers.yaml`, add a `youtubeId: 12345678901` key value pair to each talk. See also `_scripts/insert-video-ids.py`. +1. In `_data/--sessions.yaml`, add a `youtubeId: 12345678901` key value pair to each talk. See also `_scripts/insert-video-ids.py`. 2. Make sure the directory `videos//` is included in the Video Archive `toctree` in `docs/videos/index.rst`. @@ -29,25 +29,13 @@ WIP (Work In Progress) Docs on how to do this: 4. Commit the *relevant* changed files: * `docs/videos/index.rst` - * `_data/..speakers.yaml` + * `_data/--sessions.yaml` * `docs/videos///*` 5. If you want to preview locally: 1. Run `BUILD_VIDEOS=True make livehtml` and browse the new video pages at `http://127.0.0.1:8888`. -#### Troubleshooting - -If you run into trouble with broken links to video files, have a look at `_ext/fix_video_yaml.py`: - -1. Add a line at the end with the relevant places and dates. - -2. Change to the `_ext` directory and run it: - - `python fix_video_yaml.py` - -3. Commit the fixed `_data/..speakers.yaml` file. - ### Prerequisites for generating the docs locally 1. Install `python 3.9.x` using your package manager, if not installed already. You'll probably need `root` privileges to do this. diff --git a/docs/_data/prague-2021-schedule.yaml b/docs/_data/prague-2021-schedule.yaml index 53f94fabb5..b381ac61d9 100644 --- a/docs/_data/prague-2021-schedule.yaml +++ b/docs/_data/prague-2021-schedule.yaml @@ -27,7 +27,7 @@ talks_day1: title: Break (5 mins) - title: Unconference Starts - duration: '0:40' - slug: hitchhiker-s-guide-to-documentation-tools-and-processes-lukas-reu-ner + title: 'Talk removed at speakers request' - duration: '0:10' title: Break (10 mins) - duration: '0:40' @@ -97,5 +97,5 @@ talks_day2: - duration: '0:30' slug: docs-leadership-how-to-become-a-stronger-leader-for-your-team-jenn-leaver - duration: '0:15' - title: Closing address + title: Closing address - title: Conference Ends :( diff --git a/docs/_data/prague-2021-sessions.yaml b/docs/_data/prague-2021-sessions.yaml index f14ae52149..15e23a91e3 100644 --- a/docs/_data/prague-2021-sessions.yaml +++ b/docs/_data/prague-2021-sessions.yaml @@ -164,64 +164,6 @@ aren’t getting written, you’re overwhelmed and a new release is coming out. \nWhy culture matters and what it is? What is culture clash? \n How do we discover cultural indicators and work with them to promote an effective docs-first culture?

\n\n" -- title: Hitchhiker's Guide to Documentation Tools and Processes - slug: hitchhiker-s-guide-to-documentation-tools-and-processes-lukas-reu-ner - series: Write the Docs Prague - series_slug: prague - year: 2021 - youtubeId: p8-ZLqYtD5o - sketchnoteLink: https://www.flickr.com/photos/writethedocs/51631909467/in/album-72157720128594755/ - sketchnoteImage: https://live.staticflickr.com/65535/51631909467_85cea25836_b_d.jpg - speakers: - - name: Lukas Reußner - slug: lukas-reu-ner - twitter: '@lukasreussner' - website: - abstract: '

No matter if you are on earth or any other planet, it''s very likely - that one day some Vogon will approach you and ask you the ultimate question: Which - tool and process should we use for our documentation? And the worst thing about - it: the Vogon could be yourself.

- -

Fortunately, there''s a simple answer to that question: DON''T PANIC!

- -

The “small” rest of the answer will be part of this talk. It will guide you - through the maze of finding the right documentation tool(s) and the right documentation - process(s).

- -

When it comes to documentation tools, you''ll find a million out there. At - least that''s what I encountered several times when I had to decide which tool - had to be used in a new documentation project. In this talk, we won''t dive into - the nitty-gritty of specific tools. We will focus on overarching categories, such - as:

- -
    - -
  • wikis
    • - -
  • authoring systems
    • - -
  • word processors
    • - -
  • markup code toolchains
    • - -
  • media editing tools
    • - -
- -

We''ll then map those tool categories with the following types of use:

- -
    - -
  • user groups (contributors, consumers, and operators)
    • - -
  • content tasks (creating, editing, reviewing, and styling)
    • - -
  • output environments (findability, discoverability, and accessibility)
    • - -
- -

And last but not least, we''ll have a look at different documentation processes - and how they fit to our defined tool categories and types of use.

' - title: How to write a book for (and with) an open source community slug: how-to-write-a-book-for-and-with-an-open-source-community-felicity-brand series: Write the Docs Prague diff --git a/docs/_scripts/fix_video_yaml.py b/docs/_scripts/fix_video_yaml.py deleted file mode 100755 index 2174b1a8b4..0000000000 --- a/docs/_scripts/fix_video_yaml.py +++ /dev/null @@ -1,30 +0,0 @@ -from _ext.core import load_yaml -from _ext.utils import generate_video_slug -from ruamel import yaml - - -def fix_the_yaml(year, series, slug, yaml_file): - """ - This script was written by Sam to fix missing - items in the speaker YAML, used for generating videos - """ - - talks = load_yaml(yaml_file) - - for index, talk in enumerate(talks): - # print index - # print '['+ str(index) + ']' + generate_video_slug(talk) - talks[index]['year'] = year - talks[index]['series'] = series - talks[index]['event'] = series + ' ' + year - talks[index]['series_slug'] = slug - talks[index]['path'] = 'conf/' + '/'.join([talk['series_slug'], talk['year'], 'videos', generate_video_slug(talk)]) - talks[index]['slug'] = generate_video_slug(talk) - # talks[index]['speakers'] = {'details': '', 'name': talks[index]['name'], 'img_file': slugify(talks[index]['name'])+'.png', 'slug': slugify(talks[index]['name']), 'twitter': '', 'website':''} - - yaml.safe_dump(talks, open(yaml_file, 'w+'), default_flow_style=False) - - -if __name__ == '__main__': - fix_the_yaml('2018', 'Write the Docs Australia', 'australia', '../_data/2018.australia.speakers.yaml') -Ik diff --git a/docs/topics.rst b/docs/topics.rst index ae48fff8e4..3e49a09397 100644 --- a/docs/topics.rst +++ b/docs/topics.rst @@ -11,7 +11,7 @@ If you think something is wrongly categorized, please let us know. :local: :depth: 2 :backlinks: none - + Writing words ------------- @@ -36,7 +36,7 @@ Naming and terminology - |:newspaper:| `Common words and how to identify them `__ - |:movie_camera:| `Even Naming This Talk Is Hard `__ - |:movie_camera:| `Whatchamacallit: Controlled Vocabularies for Technical Writers `__ -- +- Specific writing questions ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -507,7 +507,6 @@ Doc tools - |:newspaper:| `Choosing a CCMS or a static site generator `__ - |:movie_camera:| `Two years of Markdoc: what we’ve learned about balancing developer and author experience `__ - |:newspaper:| `Standards in documentation tooling `__ -- |:movie_camera:| `Hitchhiker’s Guide to Documentation Tools and Processes `__ - |:movie_camera:| `Putting the “tech” in technical writer `__ - |:movie_camera:| `Documentation as an application: enabling interactive content that is tailored to the user `__ - |:movie_camera:| `Model-view-docs: taming large-scale documentation projects using structured data `__ diff --git a/docs/videos/prague/2021/adventures-in-setting-up-a-knowledge-system-for-a-research-group-victor-sluiter.rst b/docs/videos/prague/2021/adventures-in-setting-up-a-knowledge-system-for-a-research-group-victor-sluiter.rst index d9c1e4cac2..236cc930e7 100644 --- a/docs/videos/prague/2021/adventures-in-setting-up-a-knowledge-system-for-a-research-group-victor-sluiter.rst +++ b/docs/videos/prague/2021/adventures-in-setting-up-a-knowledge-system-for-a-research-group-victor-sluiter.rst @@ -4,5 +4,5 @@ Adventures in setting up a knowledge system for a research group .. datatemplate-video:: :source: /_data/prague-2021-sessions.yaml :template: videos/video-detail.html - :key: 8 + :key: 7 diff --git a/docs/videos/prague/2021/alchemy-in-adversity-how-to-become-better-and-more-resilient-tech-writers-in-a-turbulent-work-environment-anna-korinna-n-meth-szab.rst b/docs/videos/prague/2021/alchemy-in-adversity-how-to-become-better-and-more-resilient-tech-writers-in-a-turbulent-work-environment-anna-korinna-n-meth-szab.rst index 81d46dc890..9d75508829 100644 --- a/docs/videos/prague/2021/alchemy-in-adversity-how-to-become-better-and-more-resilient-tech-writers-in-a-turbulent-work-environment-anna-korinna-n-meth-szab.rst +++ b/docs/videos/prague/2021/alchemy-in-adversity-how-to-become-better-and-more-resilient-tech-writers-in-a-turbulent-work-environment-anna-korinna-n-meth-szab.rst @@ -4,5 +4,5 @@ Alchemy in Adversity (How to become better and more resilient tech writers in a .. datatemplate-video:: :source: /_data/prague-2021-sessions.yaml :template: videos/video-detail.html - :key: 7 + :key: 6 diff --git a/docs/videos/prague/2021/customer-feedback-is-the-fuel-in-our-engine-kevin-hwang.rst b/docs/videos/prague/2021/customer-feedback-is-the-fuel-in-our-engine-kevin-hwang.rst index 320a6b3338..cfb6d1012d 100644 --- a/docs/videos/prague/2021/customer-feedback-is-the-fuel-in-our-engine-kevin-hwang.rst +++ b/docs/videos/prague/2021/customer-feedback-is-the-fuel-in-our-engine-kevin-hwang.rst @@ -4,5 +4,5 @@ Customer Feedback is the Fuel in our Engine .. datatemplate-video:: :source: /_data/prague-2021-sessions.yaml :template: videos/video-detail.html - :key: 10 + :key: 9 diff --git a/docs/videos/prague/2021/from-travel-content-to-technical-content-my-journey-kate-santo.rst b/docs/videos/prague/2021/from-travel-content-to-technical-content-my-journey-kate-santo.rst index 69db1aaa06..2bd8d0be8f 100644 --- a/docs/videos/prague/2021/from-travel-content-to-technical-content-my-journey-kate-santo.rst +++ b/docs/videos/prague/2021/from-travel-content-to-technical-content-my-journey-kate-santo.rst @@ -4,5 +4,5 @@ From travel content to technical content: my journey .. datatemplate-video:: :source: /_data/prague-2021-sessions.yaml :template: videos/video-detail.html - :key: 9 + :key: 8 diff --git a/docs/videos/prague/2021/hitchhiker-s-guide-to-documentation-tools-and-processes-lukas-reu-ner.rst b/docs/videos/prague/2021/hitchhiker-s-guide-to-documentation-tools-and-processes-lukas-reu-ner.rst deleted file mode 100644 index ad1967cd7e..0000000000 --- a/docs/videos/prague/2021/hitchhiker-s-guide-to-documentation-tools-and-processes-lukas-reu-ner.rst +++ /dev/null @@ -1,8 +0,0 @@ -Hitchhiker's Guide to Documentation Tools and Processes -======================================================= - -.. datatemplate-video:: - :source: /_data/prague-2021-sessions.yaml - :template: videos/video-detail.html - :key: 5 - diff --git a/docs/videos/prague/2021/how-i-use-applied-linguistics-to-be-a-better-technical-writer-kat-stoica-ostenfeld.rst b/docs/videos/prague/2021/how-i-use-applied-linguistics-to-be-a-better-technical-writer-kat-stoica-ostenfeld.rst index dc3d47c50e..aacd3e8cc4 100644 --- a/docs/videos/prague/2021/how-i-use-applied-linguistics-to-be-a-better-technical-writer-kat-stoica-ostenfeld.rst +++ b/docs/videos/prague/2021/how-i-use-applied-linguistics-to-be-a-better-technical-writer-kat-stoica-ostenfeld.rst @@ -4,5 +4,5 @@ How I use applied linguistics to be a better technical writer .. datatemplate-video:: :source: /_data/prague-2021-sessions.yaml :template: videos/video-detail.html - :key: 12 + :key: 11 diff --git a/docs/videos/prague/2021/how-to-write-a-book-for-and-with-an-open-source-community-felicity-brand.rst b/docs/videos/prague/2021/how-to-write-a-book-for-and-with-an-open-source-community-felicity-brand.rst index 709cb4e3de..62d4c03b29 100644 --- a/docs/videos/prague/2021/how-to-write-a-book-for-and-with-an-open-source-community-felicity-brand.rst +++ b/docs/videos/prague/2021/how-to-write-a-book-for-and-with-an-open-source-community-felicity-brand.rst @@ -4,5 +4,5 @@ How to write a book for (and with) an open source community .. datatemplate-video:: :source: /_data/prague-2021-sessions.yaml :template: videos/video-detail.html - :key: 6 + :key: 5 diff --git a/docs/videos/prague/2021/so-you-need-to-give-bad-news-to-users-ryan-macklin-he-they.rst b/docs/videos/prague/2021/so-you-need-to-give-bad-news-to-users-ryan-macklin-he-they.rst index f294c31508..3e80bc3af4 100644 --- a/docs/videos/prague/2021/so-you-need-to-give-bad-news-to-users-ryan-macklin-he-they.rst +++ b/docs/videos/prague/2021/so-you-need-to-give-bad-news-to-users-ryan-macklin-he-they.rst @@ -4,5 +4,4 @@ So you need to give bad news to users… .. datatemplate-video:: :source: /_data/prague-2021-sessions.yaml :template: videos/video-detail.html - :key: 11 - + :key: 10