Как найти сайт по документации

Поиск ответов на вопросы и решение проблем с помощью Гугла — важнейший навык для программиста. Большинство проблем, с которыми сталкивается новичок, уже решены и описаны. Нужно лишь научиться находить эти решения и ответы.

• Сайты
• Язык
• Поисковая система
• Язык запросов
• Поиск библиотек
• Поиск по сообщению об ошибке
• Поиск по поведению
• Официальная документация

Сайты

Основные сайты с ответами на вопросы:

• GitHub
• Stackoverflow

Язык

Как показывает практика, в самом начале своего пути немалая часть программистов пытается найти ответы, задавая вопросы поисковой системе на русском языке. Иногда так можно найти ответ, но в большинстве случаев — нет. Главный язык программистов — английский, весь мир говорит именно на нем. Количество информации в англоязычном сегменте на порядки больше, чем в русскоязычном. К тому же она свежее. Учитесь формулировать свои мысли, а в случае поиска — набор слов, на английском. Заодно быстрее изучите терминологию.

Поисковая система

Связано с предыдущим пунктом. Искать нужно в Гугле. Яндекс хоть и хорош для определенных задач, все же англоязычный сегмент — не его основной рынок, и там он значительно уступает Гуглу. Например, вы заметите, что через некоторое время Гугл адаптируется к вашим запросам и начнет показывать более релевантные ссылки. Он вполне способен понять, какой язык программирования вы предпочитаете, чтобы показывать ответы, применимые именно к нему.

Еще один важный момент. Гугл даже лучше, чем специфические поиски конкретных сайтов. Если вам нужно что-то на том же Гитхабе, то лучше сформировать правильный запрос в Гугле и получить результат лучше и быстрее. Ниже, в разделе «язык запросов» об этом рассказано подробнее.

Язык запросов

Каждая поисковая система обладает языком запросов. В него входят специальные операторы, позволяющие более точно указать то, что вы хотите. Вот некоторые важные возможности:

• site:stackoverflow.com how to test react code — поиск будет произведен среди страниц сайта Stackoverflow.
• add class to element -jquery — дефисом обозначаются стоп-слова, то есть будут найдены все варианты, в которых эти слова не упоминаются.
• "immutable js" — двойные кавычки указывают на то, что нужно искать точное совпадение.

Полный список можно найти на сайте поддержки Гугл.

Поиск библиотек

Подавляющее большинство библиотек находятся (говорят, «хостятся») на Гитхабе. Предположим, понадобилось найти библиотеку для выполнения HTTP-запросов в JavaScript. Для этого можно сформировать следующий запрос: github js http client. Гугл выдаст десяток ссылок на разные репозитории. Конечно, можно использовать и язык запросов: site:github.com js http client, но чаще всего достаточно просто указать github.

Точно такая же стратегия поиска может использоваться для библиотек с известным названием: github express.

Поиск по сообщению об ошибке

Перед тем, как искать по сообщению об ошибке, нужно понять, где же тут сообщение об ошибке. Часто вывод с ошибками содержит много информации, которая хоть и относится к делу, но не является описанием той самой ошибки. Пример:

There was 1 failure:

1) AppSolutionTest::testResult with data set #2 (0, 2, 2, 1, 2)
Failed asserting that '1' matches expected 0.

/usr/src/app/tests/App/Tests/SolutionTest.php:15

FAILURES!
Tests: 3, Assertions: 3, Failures: 1.
Makefile:2: recipe for target 'test' failed
make: Leaving directory '/usr/src/app'
make: *** [test] Error 1

В этом выводе много текста, но реальное сообщение об ошибке только одно: Failed asserting that '1' matches expected 0.. Конкретно в этом случае примерно понятно, что не так и куда смотреть (в стектрейсе ниже указан файл и строчка). Но так бывает далеко не всегда. Если вам удалось точно идентифицировать сообщение об ошибке, то не лишним будет сделать еще кое-что. Часто подобные сообщения индивидуальны. В них подставляются конкретные значения каких-то параметров, относящихся именно к вашему окружению. Например, пути до файлов. Соответственно, если вы будете искать по всему тексту ошибки, то скорее всего Гугл ничего не найдет. Например, в сообщении выше такими параметрами являются '1' и 0. Если очистить фразу, то получится Failed asserting that matches expected. Именно её и надо искать. Не лишним бывает добавить имя языка: php Failed asserting that matches expected.

Поиск по поведению

Нередко сообщение об ошибке либо отсутствует, либо не может привести к правильному ответу (потому что оно — следствие, а не причина). В этой ситуации нужно проявить креативность и составить предложение на английском языке. Набор ключевых слов тоже подойдет. Если поиск не увенчался успехом, то к поисковой фразе полезно добавить site:stackoverflow.com. Stackoverflow — место, где есть ответы практически на все подобные вопросы.

Если известно, к какой библиотеке или программе относится ошибка, то полезно найти её репозиторий на Гитхабе и поизучать раздел Issues. Если ошибка действительно есть, и она актуальная, то почти наверняка о ней уже кто-то отписался.

Официальная документация

Поиск — это хорошо, но никогда не забывайте про официальную документацию используемых инструментов (в том числе языков программирования). Официальная (и не только) документация, как правило, делится на несколько видов:

1. Getting Started — небольшое (не всегда) пошаговое руководство по созданию минимально рабочей версии. Первым делом нужно искать именно этот документ. Он позволяет быстро стартануть чтобы посмотреть инструмент в деле.
2. Guides — описания компонентов рассматриваемого инструмента. Написаны в повествовательной манере, что позволяет их прочитывать от и до. По гайдам удобно изучать большие блоки.
3. API — сухая документация по всем возможным функциям приложения. В нее имеет смысл смотреть только для поиска ответов на конкретные вопросы.
4. Tutorials — в отличие от гайдов, направлены на различные варианты использования инструмента.

Кирилл Мокевнин

Секреты поиска. Как найти нужный документ .

Всем привет, это следующий урок о том, как правильно искать информацию  в сети с помощью Google. Есть одна хитрость, которая, впрочем как всегда, никаким секретом не является. Мало кто из нас задумывается, но логически это понимают все – интернет это далеко не только веб-страницы ресурсов. Это видео, фото и аудио файлы, это документы различных форматов и многое другое. Даже не всегда на том или ином ресурсе в силу каких-то обстоятельств (в том числе и по недосмотру владельца файла) мы имеем доступ к нему по прямой ссылке для скачивания. Но в сети они есть и Google их прекрасно видит. Файлы проиндексированы поисковой системой, а значит, они доступны и для нас. Так что найти нужный документ бывает проще, чем каждый из нас думает. Давайте найдём их.

Перед тем, как перейти конкретно к поиску, стоит упомянуть о специальном сервисе Google, о котором, оказывается, мало кто знает. Это страница расширенного поиска:

https://www.google.com/advanced_search?hl=ru

Я нарочно оставлю это без комментариев, там всё по-русски. Изучайте и пользуйтесь. Это, скажем, страница продвинутого поиска без знания операторов Google.

У каждого из файлов есть своё расширение, которое определяет тип программы, с помощью которой ему положено открываться. По умолчанию тип сокрыт от глаз пользователя. Но не для Google. Даже не зная названия документа полностью, вы сможете (теоретически) попытаться найти нужный документ, зная, что он имеет вид, например, документа Word из набора Microsoft Office. Вобщем, Google понимает вот такие расширения:

 Adobe Portable Document Format (PDF)

 Adobe PostScript (PS)

MacWrite (MW)

Microsoft Excel (XLS)

 Microsoft PowerPoint (PPT)

 Microsoft Word (DOC)

 Microsoft Works (WDB, WKS, WPS)

Microsoft Write (WRI)

Rich Text Format (RTF)

Text (ANS, TXT)

И некоторые другие, более специфичные. Если вы собираетесь найти нужный документ , например, обязательно в формате Word с расширением .docx, то можно попробовать задать этот параметр (без точки перед расширением) уже в поисковой строке. Это должно выглядеть так:

Название_документафайлафильмапесни filetype:тип_файла

Например:

Договор купли-продажи кактуса filetype:docx

По аналогии с известным вам исключением ненужной информации из поисковой выдачи, можно, наоборот, исключить из неё ненужные расширения и работать только с определёнными их типами. Используем, тем самым, оператор исключения «-». Например:

Договор купли-продажи кактуса -filetype:docx

Всё. В поисковой выдаче страниц с договором в формате Word не будет. Будут PDF, TXT, но не Word.

Как найти нужный документ на конкретном сайте или домене.

Нередко перед некоторыми пользователями ставится задача найти нужный документ или просто посмотреть некоторую информацию только на ресурсах, имеющих более высокую степень доверия по сравнению с остальными. Например, домены .com, .edu, .org принадлежат правительственным или образовательным учреждениям, которые имеют больший информационный вес. Или нам необходимо узнать информацию или новость из первоисточника. А про обрушение котировок на английской бирже лучше узнать не из израильского сайта, не так ли? Потому лучше было зондировать именно английские источники информации – это доменная зона британцев .uk. Или канадцев — .ca. Или французов – fr. И так далее.

Так вот, чтобы заняться поиском только по конкретной доменной зоне, укажите тип домена в поисковом запросе с помощью оператора “site:”. Например:

site:.edu (не забудьте точку перед названием домена)

И при наборе информации в определённой зоне:

Do it yourself.:ru

Google будет искать результаты только в русскоязычном интернете (рунете).

По аналогии с доменной зоной можно сократить место поиска до конкретного веб-сайта. Например, если нужно прочитать справку о том или ином событий в операционной системе Windows, есть смысл обратиться к первоисточнику. Ищите в пределах только официальной справки от Microsoft на официальном сайте. Для этого используйте тот же самый оператор в таком виде:

Ошибка 000240767 site:www.microsoft.com (точку перед адресом ставить нельзя!)

Все найденные результаты будут касаться только этого сайта.

Успехов

Edit me

Вместо того, чтобы подходить к теме публикации в перспективе, начнем с некоторых конкретных примеров и перейдем к формулированию общих принципов. Ниже приведено более 100 открыто доступных API-интерфейсов REST, которые можно просмотреть для изучения шаблонов и примеров. Много других API можно найти, просматривая programmableweb.com.

Просмотрим некоторые из этих сайтов документации, чтобы получить представление о разнообразии, а также попытаемся определить общие закономерности. В этот список включены не только впечатляющие документы, но и документы, которые выглядят так, как будто они были созданы стажером отдела, изучающим HTML. Разнообразие в списке демонстрирует множество опций для публикации инструментов и подходов, а также терминологию. Кажется, что почти каждый делает свои документы API по-своему, со своим брендингом, организацией и стилем.

1. Shopgate API docs
2. Google Places API docs
3. Twitter API docs
4. Flickr API docs
5. Facebook’s Graph API docs
6. Youtube API docs
7. eBay API docs
8. Amazon EC2 API docs
9. Twilio API docs
10. Last.fm API docs
11. Bing Maps docs
12. gpodder.net Web Service docs
13. Google Cloud API docs
14. Foursquare Places API docs
15. Walmart API docs
16. Dropbox API docs
17. Splunk API docs
18. Revit API docs
19. Docusign API docs
20. Geonames docs
21. Adsense API docs
22. Box API docs
23. Amazon API docs
24. Linkedin REST API docs
25. Instagram API docs
26. Zomato API docs
27. Yahoo Social API docs
28. Google Analytics Management API docs
29. Yelp API docs
30. Lyft API docs
31. Facebook API docs
32. Eventful API docs
33. Concur API docs
34. Paypal API docs
35. Bitly API docs
36. Callfire API docs
37. Reddit API docs
38. Netvibes API docs
39. Rhapsody API docs
40. Donors Choose docs
41. Sendgrid API docs
42. Mailchimp docs
43. Basecamp API docs
44. Smugmug API docs
45. NYTimes API docs
46. USPS API docs
47. NWS API docs
48. Evernote API docs
49. Stripe API docs
50. Parse API docs
51. Opensecrets API docs
52. CNN API docs
53. CTA Train Tracker API
54. Amazon API docs
55. Revit API docs
56. Citygrid API docs
57. Mapbox API docs
58. Groupon API docs
59. AddThis Data API docs
60. Yahoo Weather API docs
61. Glassdoor Jobs API docs
62. Crunchbase API docs
63. Zendesk API docs
64. Validic API docs
65. Ninja Blocks API docs
66. Pushover API docs
67. https://pushover.net/api
68. Pingdom API docs
69. Daily Mile API docs
70. Jive docs
71. IBM Watson docs
72. HipChat API docs
73. Stores API docs
74. Alchemy API docs
75. Indivo API 2.0 docs
76. Socrata API docs
77. Github API docs
78. Mailgun API docs
79. RiotGames API docs
80. Basecamp API docs
81. ESPN API docs
82. Snap API docs
83. SwiftType API docs
84. Snipcart API docs
85. VHX API docs
86. Polldaddy API docs
87. Gumroad API docs
88. Formstack API docs
89. Livefyre API docs
90. Salesforce Chatter RESt API docs
91. The Movie Database API docs
92. Free Music Archive API docs
93. Context.io docs
94. CouchDB docs
95. Smart Home API (Amazon Alexa) docs
96. Coinbase docs
97. Shopify API docs
98. Authorize.net docs
99. Trip Advisor docs
100. Pinterest docs
101. Uber docs
102. Spotify API
103. Trello API
104. Yext API
105. Threat Stack API docs
106. Strava API
107. Plaid API
108. Paymill API
109. Rundown API
110. Zype API

Каталог сайтов документации API можно найти на Programmableweb.com docs. Там можно просматривать тысячи документов по веб-API в различных категориях.

На сайте Programmableweb только открытые веб-API, то есть API-интерфейсы, к которым можно получить доступ в Интернете (что также означает, что обычно это REST API). Здесь нет бесчисленных внутренних API-интерфейсов с брандмауэром, которые многие компании предоставляют платным клиентам. Есть еще много тысяч частных API, о которых большинство из нас никогда не узнает.

👨‍💻 Практическое занятие: Поиск общих паттернов на сайтах API документации

В этом упражнении попробуем определить общие шаблоны на сайтах документации API.

1. Открываем наш список сайтов
2. Выбираем 4-5 разных API (любые из списка)
3. Ищем шаблоны или общие черты этих сайтов API. Например, можно поискать любой из следующих шаблонов:

• структура;
• брендинг (между документами и маркетинговым сайтом);
• объемные примеры кода и подсветка синтаксиса;
• длинные страницы;
• интерактивность API (например, как API Explorer);
• инструментарий docs-as-code;

1. Обратим внимание на отклонения от шаблонов, такие как следующие:

• PDF;
• перевод;
• видео инструкции;
• функции комментирования;
• множественные выводы для роли

1. Сделаем заметки по своим наблюдениям на будущее.

В следующем разделе мы рассмотрим Шаблоны проектирования сайтов API документации Из сделанных заметок посмотрим, соответствуют ли выделенные шаблоны тем, которые мы наблюдали на выбранных сайтах API.

🔙

Go next ➡

• Статус документа:

  Устаревший

  Категории:

  Регламенты

  Дата принятия:

  09.03.2005

  Nid:

  387

• Статус документа:

  Актуальный

  Категории:

  Указы Президента

  Номер документа:

  521-рп

  Дата принятия:

  24.09.2007

  Nid:

  31

• Статус документа:

  Актуальный

  Категории:

  Указы Президента

  Номер документа:

  627

  Дата принятия:

  02.06.2001

  Дата вступления в силу:

  26.02.2009

  Nid:

  32

• Статус документа:

  Устаревший

  Категории:

  Положения

  Nid:

  386

• Статус документа:

  Актуальный

  Категории:

  Информационные письма Росархива

  Номер документа:

  II/62-А

  Дата принятия:

  19.01.2010

  Nid:

  621

• Статус документа:

  Актуальный

  Категории:

  Приказы Росархива

  Номер документа:

  34

  Дата принятия:

  26.02.2019

  Nid:

  5011

• Статус документа:

  Актуальный

  Категории:

  Соглашения о сотрудничестве

  Дата принятия:

  16.08.2005

  Nid:

  150

• Статус документа:

  Актуальный

  Категории:

  Соглашения о сотрудничестве

  Дата принятия:

  07.12.2004

  Nid:

  151

• Статус документа:

  Актуальный

  Категории:

  Соглашения о сотрудничестве

  Дата принятия:

  03.12.2003

  Nid:

  152

• Статус документа:

  Актуальный

  Категории:

  Соглашения о сотрудничестве

  Дата принятия:

  18.11.2003

  Nid:

  153

• Статус документа:

  Актуальный

  Категории:

  Соглашения о сотрудничестве

  Дата принятия:

  02.07.2003

  Nid:

  154

• Статус документа:

  Актуальный

  Категории:

  Соглашения о сотрудничестве

  Дата принятия:

  02.10.2001

  Nid:

  155

• Статус документа:

  Устаревший

  Категории:

  Коллективный договор

  Дата принятия:

  20.03.2006

  Nid:

  187

• Статус документа:

  Устаревший

  Категории:

  Коллективный договор

  Номер документа:

  1

  Дата принятия:

  19.03.2009

  Nid:

  188

• Статус документа:

  Устаревший

  Категории:

  Положения

  Nid:

  302

• Статус документа:

  Устаревший

  Категории:

  Положения

  Nid:

  303

• Статус документа:

  Устаревший

  Категории:

  Приказы Росархива

  Номер документа:

  35

  Дата принятия:

  08.10.2004

  Nid:

  310