#67 Tech Writer żegna "foo", "bar" i "baz", czyli jak tworzyć dobre próbki kodu
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/
Paweł i Michał przywitają się i rozmawiają o Międzynarodowym Dniu Pisania Próbek Kodu.
Michał opisuje swoją frustrację z użyciem foo, bar i baz w próbkach kodu i pyta o zdanie Pawła na ten temat.
Paweł opisuje różnice między dokumentacją przeznaczoną dla użytkowników końcowych a programistów i podkreśla ważność dobrej dokumentacji technicznej.
Paweł podziela się przykładowymi stronami z dobrą dokumentacją, takimi jak React.dev i DocuSaurus.
Paweł i Michał debatują o używaniu placeholderów w próbkach kodu i opisują swoje preferencje.
Michał przedstawia alternatywy do placeholderów, takie jak komentarze w kodzie i opisy przed próbką kodu.
Paweł podzieli się przykładem z dokumentacji, który prowadzi do problemów z domenami DNS i debatuje nad tym z Michałem.
Paweł i Michał omawiają różne podejścia do rozwiązania problemu z placeholderami w kodzie i opisują swoje preferencje.
Paweł i Michał kontynuują debatę nad dobrocią kodu w próbkach, opisując różne podejścia do ich tworzenia i uaktualniania.
Ważność zespołu w tworzeniu i walidacji próbek kodu oraz problem z brakiem dostępu do środowiska testowego.
Opis narzędzi do podkreślania składni i dodawania interaktywnych funkcji do próbek kodu, np. przycisk kopii.
Opis nowego rozwiązania w DocuZaurusie umożliwiającego interaktywne edytowanie próbek kodu.
Wskazówki i linki do artykułów na temat pisania dobrze strukturyzowanych próbek kodu.
Podsumowanie i wyrażenie życzenia do czynienia tylko z dobrymi przykładami w przyszłości.
Rozdziały i streszczenia generowane automatycznie. Pełna transkrypcja nie jest publikowana — wyszukaj frazę, aby zobaczyć dopasowane fragmenty.
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/