https://passo.uno/tech-writers-letter-to-developers/
Хороший канал щодо перекладу і локалізації:
t.me/pereklad_lokalizatsiya
Щодо недоліків статичної генерації сайтів: якщо треба генерувати 100К сторінок, то треба використовувати швидкий генератор типу Hugo, який впорається з цією операцією не за години, а за хвилини. Із тих, що я пробував генераторів SSG, Hugo найшвидший.
Так буває, що техрайтер суміщає обов’язки БА. Але це окремий кейс, а не правило. Часто-густо техрайтерів намагаються використовувати не за призначенням )) Наприклад: вести мітінг ноутс на зустрічах, робити презентації в пауер пойнті, писати копірайтерські тексти чи статті на ДОУ замість, наприклад, архітектора чи СТО ))
«Technical Writer зобов’язаний мати гарні знання в тій галузі, про яку пише...» — не зовсім так. Іноді треба писати про досить специфічний домен. Гарні знання у цій сфері потрібно отримувати роками. Важливо вміти правильно опитати носіїв знань і викласти це зрозумілою мовою для читача документації.
«Якщо ж матеріал „від клієнта — розробнику“, то технічний письменник оцінює потреби клієнта, а потім доносить це до розробників у зрозумілій для них формі у вигляді специфікації чи технічного завдання.» — це збір вимог, що є завданням бізнес-аналітика.
Desing and Development принципи виправте очепятку. Design. Загалом дуже корисна стаття: стисло, без води. І це лише верхівка айсберга.
Дякую за детальне технічне пояснення цього рішення! Виглядає дуже складно. Із подібних рішень я стикався з Azure Data Factory, Databricks, про яке ви згадуєте як альтернативу. ADF набагато простіше на мою думку. Процес налаштування схожий візуально на кубики, з якими впорається навіть домогосподарка )) При цьому ви зможете налаштувати ті самі процеси трансформації даних ETL зі скриптами на пітоні та запускати їх за розкладом.
Тому ще найпростіше через нього опублікувати свій сайт в інтернеті. Ще можу рекомендувати Vercel, який дуже схожий на Netlify. На сайті Docusaurus є документація, як деплоїти на GitHub Pages: docusaurus.io/...deploying-to-github-pages
Мені цей процес видається трохи складним, починаючи з вимогу мати дві гілки: одна для коду, а інша — для деплоя. У Netlify все робиться натисканням кнопки кілька разів. У випадку GitHub pages потрібно буде ще внести зміни у файл конфігурації docusaurus.config.js.
Свого часу я перепробував багато різних способів деплоїти та хостити сайт: Firebase, Azure, GitLab Pages. Усюди процес був трохи заплутаний і спрацьовував не з першого разу. Можливо, зараз щось змінилося або з’явились нові рішення. Буду радий почути дізнатися щось нове!
Я рекомендую те, чим користуюся сам. Якщо комусь зручніше користуватися Notepad++ — будь ласка. Але чи є там такий набір розширень (extensions), як-от лінтер Vale для перевірки текстів на відповідність вимогам стайл гайдів? Markdownlint і багато інших корисних розширень.
Читабельний код потрібен ще і техрайтерам. Їм іноді приходиться зазирати в код. І яку вдячність вони відчувають до розробників, якщо ті залишили їм хоч якісь коментарі, що той робить.
Чудова стаття, дякую! Лише додам, що важко знайти нормальні курси. Краще знайти нормального ментора.
А документація для вашого API планується? Заявлено public API, але на сайті немає документації.
Чудова стаття, яка стане в нагоді не лише початківцям, а й досвідченим фахівцям, які пишуть документацію. MadCap Flare ❤️
Дуже дякую!
Радий, що стаття стала в пригоді. Можу також рекомендувати спробувати зробити сайт на MkDocs Material. Цей генератор на рівні з Докузаурусом рекомендую для документації.