Переведенный курс Тома Джонсона по документированию API обзавёлся сайтом:

https://starkovden.github.io/

#API #resource #ru

Гигантский монструозный лонгридище из 7 частей от "Богов Поиска" - Algolia. Рассказывают о том как они редизайнили свою документацию, от причин зачем это всё и UI/UX решений, вплоть до самого писательства и nitty-gritty технических моментиков.

1. Redesigning Our Docs – Part 1 – Why
2. Redesigning our Docs – Part 2 – Making Technical Content Readable for Everybody
3. Redesigning Our Docs – Part 3 – The UX/UI Phase
4. Redesigning Our Docs – Part 4 – Building a Scalable CSS Architecture
5. Redesigning Our Docs – Part 5 – Building an Interactive InstantSearch Showcase
6. Redesigning our Docs – Part 6 – The processes and logistics of a large scale project
7. Redesigning our Docs – Part 7 – What’s next to come

Бонусным треком статья от них же про API документацию с посылом и о том, что счастье не в тулзах с помощью которых это всё делается, а в деньгах, которые за это платятся, а в самом подходе к структурированию этой информации и в самом контенте. Иными словами тулинг должен заботить пусть и не в последнюю очередь, но и уж точно не в первую. Adapt the tool to the content, not vice versa.

Good API Documentation Is Not About Choosing the Right Tool

#API #en #article #resource #uiux

ReadMe (которые personalized, interactive developer hubs) ведут офигенский documentation-related блог, рекомендую!

Сегодня попалась на глаза их обширная статья о том как начать вкатываться в Swagger + OpenAPI документацию. Темплейты, бест поактисы, тулзы и примеры. Всё к вашим услугам! Нормально подойдет для базовых познаний что там да как.

Бонус трек - Mockoon, мокалка API, которая умеет всё локально (No remote deployment, no account required, open source.), еще и кроссплатформенная.

#API #example #resource #article #en

Ноушн запускает доступ к API.

Готовимся к полному завоеванию Ноушном всего мира knowledge-sharing'а

https://www.notion.so/api-beta

#API #knowledgemanagement

Курс по документированию API от Тома Джонсона теперь доступен в удобных форматах!

1. PDF
2. EPUB
3. MOBI

⛄️

#API #en #book

👅 Языки:

#ru | #en

👷 Карьера:

#career — советы и всемозможные статьи о карьере техписателя
#conference — техписательские конференции, их записи и заметки
#resources — ресурс для саморазвития
#article — полезная статья, которая учит чему-то клёвому, что позволит стать более лучшим писателем
#vacancy — интересная вакансия или что-то связанное с наймом
#video — видео, видос, видосичек, видосюлька. И подкасты!
#book — книга/хендбук
#courses — курсы, программы для технических писателей

🛠 Технологии:

#tool — полезная утилита/приложение
#changelog — все о чейнджлогах, примеры, правила
#markdown — все о языке разметки Markdown
#reStructuredText — все о языке разметки reStructuredText
#asciidoc — все о языке разметки asciidoc
#LaTeX — все систему набора и вёрстки и язык разметки LaTeX
#ide — среды разработки и все что с ними связано
#vscode — все о Visual Studio Code, настройка, плагины, хитрости
#SSG — JAMStack, генераторы статических сайтов, Hugo, Jekyll, Antora, etc.
#testthedocs — тестирование документации, линтинг
#API — про документирование API, примеры, лайфхаки, подсказки
#diagram — про диаграммы (много про diagrams as a code), mermaid, UML
#screenshot — все про скриншоты, утилиты, сервисы и красивенькие фотоснимки экрана
#ai — про GPT, GitHub Copilot и прочее, где ИИ помогает нам писать

🧺 Общее:

#tonevoice — о правилах общения в документации
#language — что-то конкретно о языке, в основном английский
#legal — юридическая документация, лицензии
#styleguide — все о стилях и правилах
#DocsAsCode — все про подход к документации как к коду
#example — примеры документации (хорошие и плохие)
#uiux — интерфейсы, текст в интерфейсах, пользовательский опыт
#knowledgemanagement — менеджмент знаний, хранилища, тулзы, техники, советы и наблюдения
#versioning — про версионирование
#accessibility — все об аксессебилити в документации
#checklist — чеклист/шпаргалка
#vintage — винтажная документация, старые компьютеры, софт, техника, игры
#visual — про визуальную составляющую документации
#metrics — все о метриках документации
#random — что-то совсем косвенно относящееся к техписательству, юморески

Предлагайте новые хэштеги в комментариях!