Документация нужна для обнаруживаемости
Этот документ призван разъяснить чрезвычайно важный момент в написании документации, который должен усвоить каждый, кто хочет внести вклад новыми страницами.
Документация нужна для обнаруживаемости!
Это означает, что документация систем должна не включать вещи вроде:
- Конкретные API методов, которые обязательно изменятся
- Перечисление и объяснение каждого поля случайного прототипа
- Объяснение деталей кода, которые в 100 раз лучше передаются через комментарии к коду и xmldocs
Когда кто-то ищет «документацию» по теме, на самом деле он может искать две разные вещи. У него может быть лишь общее представление о том, что он хочет сделать, и он ищет как — ищет, какие инструменты и системы доступны для начала и как они складываются в единое целое. Именно эту услугу и призван предоставлять такой сайт документации в формате markdown.
Или же он может искать что — конкретные детали API, с которыми он работает, какие методы он может вызывать, что передавать в эти методы, переопределения абстрактных методов и т. д. Лучше всего с этим справляется ваша IDE, потому что C# является статически типизированным языком, и эта информация очень легко доступна любому программисту. Поиск по файлам также очень мощный, когда ваша IDE не может помочь (например, для поиска доступных полей данных YAML).
Хорошо:
Если вы пытаетесь достичь X, лучший способ лежит через GlubbySystem...
...
Сначала создайте GlubbyPrototype в YAML, затем в своей собственной системе вызывайте методы у GlubbySystem
чтобы создать и зарегистрировать glubber...
Плохо:
Вот поля, доступные в GlubbyPrototype:
glubPotency: это поле является integer
glubDecay: это поле является timespan
glubberDelay: это поле является timespan
glubTargets: это поле является dictionary из string в entityuid цели glub
Нет никакой гарантии, что все страницы документации здесь на самом деле следуют этой концепции! Многие из них очень, очень старые. Если вам хочется их переписать, вперёд!