Pisanie dokumentacji jest trudne, co do tego nie mamy wątpliwości. Programiści nie raz w swojej karierze napotykają sytuację, w której muszą opisać jakąś procedurę lub stworzyć README. O ile aktualizacja istniejącej dokumentacji jest do przejścia, to napisanie czegoś od zera może wydawać się zadaniem nie do wykonania.

Czy na pewno? Okazuje się, że deweloperzy mogą wiedzieć więcej o pisaniu dokumentacji niż im się wydaje. Wystarczy tylko zmienić sposób myślenia na temat tego procesu i poznać kilka podstawowych zasad tech writingu.

W naszej rozmowie łączymy filozoficzne rozważania o podobieństwach pomiędzy kodowaniem i pisaniem dokumentacji z praktycznymi wskazówkami dla programistów na temat pisania dokumentacji.

Dźwięki wykorzystane w audycji pochodzą z kolekcji "107 Free Retro Game Sounds" dostępnej na stronie https://dominik-braun.net, udostępnianej na podstawie licencji Creative Commons license CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/).

Informacje dodatkowe:

• Konferencja Web Summer Camp: https://websummercamp.com
• "Democratizing Design for Better Collaboration", Stephanie Stimac: https://www.youtube.com/watch?v=ZATMLWKIObA&list=PLsL1X_98-_XDD1Lm32Sk8HPyPgZ0e1JeX&index=3
• "Guard Clause", DevIQ: https://deviq.com/design-patterns/guard-clause
• Colima: https://github.com/abiosoft/colima
• "#67 Tech Writer żegna "foo", "bar" i "baz", czyli jak tworzyć dobre próbki kodu", Tech Writer koduje: https://techwriterkoduje.pl/blog/2024/6/26/67
• "Structured writing", Wikipedia: https://en.wikipedia.org/wiki/Structured_writing
• "Golden rules for writing docs", Tech Writer koduje: https://techwriterkoduje.pl/golden-rules
• "How did over 300 skeptics start writing docs?", Rafał Pawlicki (soap! 2018): https://www.youtube.com/watch?v=FpcSJa5rEpE
• "Style guide, czyli księga stylu: jak trzymać fason w UX writingu", UX Writing Wiwisekcja: https://open.spotify.com/episode/4jGjLxt8igNqOCmgb8tOmi?si=33167b19519549bb
• "Top 10 tips for Microsoft style and voice", Microsoft Writing Style Guide: https://learn.microsoft.com/en-us/style-guide/top-10-tips-style-voice
• "Software Engineering at Google", Titus Winters, Tom Manshreck, Hyrum Wright: https://www.oreilly.com/library/view/software-engineering-at/9781492082781/

Próbki kodu to kluczowy element dokumentacji, a w szczególności dokumentacji dla deweloperów. Dlatego uważamy, że "foo", "bar" i "baz" muszą odejść.

Jako kodujący Tech Writerzy spotykamy się zarówno z dobrymi jak i kiepskimi przykładami, dlatego postanowiliśmy podsumować naszą wiedzę i doświadczenia w tym zakresie i zastanowić się jak tworzyć próbki, które są pomocne i łatwe do zrozumienia.

Rozmawiamy o dobrych i złych praktykach, o potencjalnych problemach i rozwiązaniach oraz, oczywiście, o narzędziach, które możemy wykorzystać, żeby nasze próbki były jeszcze lepsze.

Dźwięki wykorzystane w audycji pochodzą z kolekcji "107 Free Retro Game Sounds" dostępnej na stronie https://dominik-braun.net, udostępnianej na podstawie licencji Creative Commons license CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/).

Informacje dodatkowe:

• "Never Use Foo, Bar, Baz, etc. in Software Documentation", Tech Your Chance: https://www.techyourchance.com/never-use-foo-bar-baz/
• "Online resources to learn how to code", StackOverflow Developer Survey 2022: https://survey.stackoverflow.co/2022/#section-learning-to-code-online-resources-to-learn-how-to-code
• "Online resources to learn how to code", StackOverflow Developer Survey 2023: https://survey.stackoverflow.co/2023/#section-learning-to-code-online-resources-to-learn-how-to-code
• "Default behaviour sticks (And so do examples)", Thinkst Thoughts: https://blog.thinkst.com/2023/08/default-behaviour-sticks-and-so-do-examples.html
• "Code blocks", Docusaurus: https://docusaurus.io/docs/markdown-features/code-blocks
• rundoc: https://eclecticiq.github.io/rundoc/
• "Code samples", Google developer documentation style guide: https://developers.google.com/style/code-samples
• "Creating sample code", Google Technical Writing: https://developers.google.com/tech-writing/two/sample-code
• "Guidelines for writing code examples", MDN: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide
• "Write excellent code examples", The Developer Advocacy Handbook: https://developer-advocacy.com/write-excellent-code-examples
• Dokumentacja React.js: https://react.dev/
• Dokumentacja Yarn: https://yarnpkg.com/
• Dokumentacja react-router: https://reactrouter.com/en/main
• Prism.js: https://prismjs.com/
• Docusaurus: https://docusaurus.io/
• Storybook: https://storybook.js.org/

W tym miesiącu nasz podcast obchodzi 5. urodziny. Przez ten czas nagraliśmy ponad 60 odcinków, w których rozmawialiśmy o wielu rzeczach związanych z techniczną stroną tworzenia dokumentacji, ale nigdy o tym co się dzieje za kotarą, o naszych tajnikach i technikach.

Dlatego z okazji jubileuszu, postanowiliśmy opowiedzieć Wam dlaczego w ogóle zaczęliśmy nagrywać, skąd czerpiemy pomysły, czy pracujemy ze scenariuszem czy raczej jesteśmy mistrzami improwizacji, jakiego sprzętu i oprogramowania używamy, jak działa nasza strona i czy w ogóle ktoś nas słucha.

Dźwięki wykorzystane w audycji pochodzą z kolekcji "107 Free Retro Game Sounds" dostępnej na stronie https://dominik-braun.net, udostępnianej na podstawie licencji Creative Commons license CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/).

Informacje dodatkowe:

• "#1 Docs like code - rozważania praktyczne i filozoficzne", Tech Writer koduje: https://techwriterkoduje.pl/blog/2019/5/14/1
• "Polski podkast dla techwriterów!", Techwriter.pl: https://techwriter.pl/polski-podkast-dla-techwriterow/
• Riverside.fm: https://riverside.fm/
• Zencastr: https://zencastr.com/
• Audacity: https://www.audacityteam.org/
• Spotify for Podcasters (dawniej Anchor.fm): https://podcasters.spotify.com/
• "RSS", Wikipedia: https://pl.wikipedia.org/wiki/RSS
• Mikrofon Novox NC-1: https://novox.pl/
• "#51 Tech Writer buduje stronę dla podcastu, czyli praktyczne zastosowanie Next.js", Tech Writer koduje: https://techwriterkoduje.pl/blog/2023/2/26/51
• "MeetContentKRK zaprasza na Content Day", techwriter.pl: https://techwriter.pl/meet-content-krk-content-day/