Jak czytać i pisać dokumentację oprogramowania

Marcin Sędłak-Jakubowski

Hejka

1. Nauczyciel angielskiego

... Bylejaki Pythonista

2. Technical writer

Rekrutujemy!

grnh.se/a5faec9d2

Po co mi dokumentacja?

By móc użyć swojego kodu 6 miesięcy później

By inni używali twojego kodu

By inni pomagali ulepszyć twój kod

Rodzaje dokumentacji

1. Tutorial

  • Zorientowany na naukę
  • Jest rodzajem lekcji
  • Analogia: uczenie dziecka gotować

2. How-to guide

  • Zorientowany na cel
  • Pokazuje jak rozwiązać problem
  • Jest zestawem kroków
  • Analogia: przepis w książce kucharskiej

3. Wyjaśnienie

  • Zorientowane na zrozumienie
  • Wyjaśnia
  • Opisuje kontekst i tło
  • Analogia: artykuł o społecznym aspekcie gotowania

4. Technical reference

  • Zorientowane na informacje
  • Opisuje działanie
  • Jest szczegółowe i konkretne
  • Analogia: artykuł encyklopedyczny
Dobre kiedy się uczymy Dobre kiedy pracujemy
Praktyczne kroki Tutorial How-to guide
Wiedza teoretyczna Wyjaśnienie Reference

Jak czytać dokumentację?

Scenariusz 1:

Wstępne rozeznanie

man pgrep

Scenariusz 2:

Szybki start

Scenariusz 3:

Pomocy, utknąłem!

Cechy dobrej dokumentacji

Ma być

Ma być poprawna

Architektura informacji

Every page is page one

Plan
Pisanie
Redakcja

Działające przykłady

Żarty na bok

Na ratunek: mikrohumor

Jak tworzyć dokumentację?

Zacznij od README

Style guide

Style Guide

Narzędzia

HTML, XML

np. MadCap Flare

Online

np. Atlassian Confluence

Prosty markup

Markdown / reStructuredText

Static Site Generators

Docs-as-Code

Dokumentacja jak kod

  • Issue trackers
  • Version control (Git)
  • Plain text markup (Markdown, reStructuredText, Asciidoc)
  • Code reviews
  • Automated tests

Co robię jako technical writer

Szczęśliwi użytkownicy

Chcę dorzucić cegiełkę do open source

Dokumentacja!

Linki na koniec

Źródła grafik: Unsplash lub Pixabay, chyba że podane przy zdjęciu

Jak czytać i pisać dokumentację oprogramowania

Marcin Sędłak-Jakubowski

Jak czytać i pisać dokumentację oprogramowania

By Marcin Sędłak-Jakubowski

Jak czytać i pisać dokumentację oprogramowania

Ucząc się programować, od razu chciałem dokładać swoją pracę do używanych przez siebie projektów open source. Niestety, umiałem za mało, żeby rozumieć i zmieniać cudzy kod. Na szczęście odkryłem, że mogę pomóc zaganianym programistom z redakcją dokumentacji i dodawaniem brakujących przecinków i usuwaniem przymiotników! Umiejętność czytania dokumentacji przydaje się nie tylko twórcom, ale i użytkownikom oprogramowania. Z kolei umiejętność zrozumiałego pisania przydaje się nie tylko w IT.

  • 87
Loading comments...

More from Marcin Sędłak-Jakubowski