Я был редактором дольше, чем я был разработчиком, поэтому эта тема для меня — настоящая корневая проблема. 🥁 Когда я вижу отличный проект с плохо написанными документами, он попадает рядом с /домой . Хорошо, хорошо, я закончил.
Я помогаю Открыть проект безопасности веб-приложения (OWASP) С их Руководство по тестированию веб-безопасности (WSTG) . Я был недавно поручено написать Руководство по стилю и шаблон статьи, который показывает, как написать техническую инструкцию для тестирования программных приложений. Вы можете найти Руководство по стилю здесь Отказ
Я думал, что части гида принесет пользу большему количеству людей, чем просто участникам Оуда, поэтому я делюсь здесь.
Многие из проектов, в которых я участвую, — это открытый источник. Это замечательный способ для людей поделиться решениями и создавать идеи друг друга. К сожалению, это также отличный способ для несоответствия и несуществующих слов, чтобы поймать. Вот выдержка гида с некоторыми ошибками, которые я заметил, и как вы можете исправить их в ваших технических документах.
Используйте правильные слова
Ниже приведены часто используемые словами и как их исправить.
и/или
Хотя иногда используется в юридических документах, и/или приводит к двусмысленности и путанице в техническом письме. Вместо этого используйте или , который на английском языке включает и Отказ Например:
Плохое: «Код выводит номер ошибки и/или описание. » Хорошо: «Код выводит номер ошибки или описание».
Последнее предложение не исключает возможности иметь как номер ошибки и описание.
Если вам нужно указать все возможные результаты, используйте список:
» Код выводит номер ошибки или описание или оба. «
Frontend, Backend
Хотя это правда, что английский язык развивается со временем, это еще не слова.
Ссылаясь на существительные, используйте Передний конец и Задний конец Отказ Например:
Безопасность одинаково важно на переднем конце, как на заднем конце.
Как описательное наречие, используйте детепэнированный Фронт-конец и Задний конец Отказ
Оба предельные разработчики и задневские разработчики несут ответственность за безопасность приложений.
Whitebox, BlackBox, GreyBox
Это не слова.
Как существительные, используйте Белая коробка , черный ящик и Серая коробка Отказ Эти существительные редко появляются в связи с кибербезодой.
Мой кот любит прыгать в эту серую коробку.
Как наречия, используйте дефис Белокосная коробка , черный ящик и серая коробка Отказ Не используйте капитализацию, если слова не находятся в заголовке.
В то время как тестирование белого ящика включает в себя знание исходного кода, тестирование черных коробок не. Тест серых коробок где-то между ними.
т.е. например
Это буквы.
Аббревиатура I.E. Относится к латинскому ID EST , что означает «Другими словами». «Аббревиатура например для Exempli Gratia , перевод к «Например. » Использовать их в предложении:
Напишите, используя правильный английский, то есть правильное правописание и грамматику. Используйте общие слова на необычных, например, «Узнайте» вместо «Glean».
и т.д
Это также буквы.
Латинская фраза ET CETERA переводится на «а остальное. «Это сокращено и т. Д. и обычно размещается в конце списка, который кажется избыточным для завершения:
Авторы WSTG, такие как цвета радуги, такие как красный, желтый, зеленый и др.
В техническом письме, использование и Т. Д. проблематично. Предполагается, что читатель знает, о чем вы говорите, и они не могут. Фиолетовый является одним из цветов радуги, но приведенный выше пример не говорит вам, если фиолетовый цвет — это цвет, который вроде авторы WSTG.
Лучше быть явным и тщательным, чем сделать предположения читателя. Используйте только и т. д. Чтобы избежать завершения списка, который был предоставлен в полном объеме ранее в документе.
… (эллипсис)
Марк пунктуации эллипса может указывать на то, что слова были оставлены из цитаты:
Линус Торвальд однажды сказал: «Как только вы поймете, что документация должна смеяться над … Тогда и только тогда вы достигли уровня, где вы можете безопасно прочитать его и попытаться использовать его, чтобы на самом деле реализовать драйвер».
Пока упущение не изменяет значение цитаты, это приемлемое использование эллипсиров в WSTG.
Все остальные виды использования эллипсовых, таких как указывают на незаконченную мысль, нет.
бывший
Хотя это слово, скорее всего, не слово, которое вы ищете. Слово бывший имеет особое значение в сфере финансов и коммерции и может относиться к человеку, если вы обсуждаете свои прошлые отношения. Ни одна из этих тем не должна появиться в WSTG.
Аббревиатура бывший. Может использоваться для означающего «пример» ленивыми писателями. Пожалуйста, не лените и пишу пример вместо.
Иди и напишите документы
Если эти напоминания полезны, пожалуйста, поделитесь их свободно и используйте их при написании собственных readmes и документации! Если есть некоторые, я пропустил, я бы хотел знать.
И если вы здесь для комментариев …
Если вы хотите помочь вносить вклад в OwaSP WSTG, пожалуйста, прочитайте Руководство вклада Отказ Смотрите Полное руководство здесь Отказ
Оригинал: «https://dev.to/victoria/word-bugs-in-software-documentation-and-how-to-fix-them-41a1»