14.06.2017 Экспертиза, Открытый код/LinuxХорошая документация играет решающую роль в открытом проекте. Это подтверждают как многочисленные эксперты, так и результаты проведённого GitHub исследования, в котором 93% респондентов отметили важность этой составляющей. Очевидно, что основная сложность написания документации заключается в том, что она должна быть не только полной, но и разнообразной. Технический писатель Red Hat Роберт Кратки на сайте OpenSource.com рассказывает об одном из возможных способов решения этой проблемы. Есть множество подходов к написанию документации, но все они так или иначе могут быть отнесены всего к двум категориям: описание возможностей продукта; описание действий, необходимых для решения конкретных задач. Оба подхода используются на практике даже в рамках одного проекта, поскольку ориентированы на различную аудиторию. Вероятнее всего, в идеальном случае следует применять и тот, и другой, если это позволяют ресурсы. Предпочесть какой-то один вряд ли возможно. Типичное man-руководство в UNIX-системе — хороший пример документации, содержащей исчерпывающий список всех функций программы с примерами их практического применения, что опытному пользователю, вероятнее всего, будет достаточно. Критерии качества таких инструкций — полнота и точность. С другой стороны, классический пример документации, ориентированной на достижение конкретной цели — книга кулинарных рецептов. Когда она хорошо написана, то даже новичок сможет приготовить относительно съедобное блюдо, если будет в точности ...
читать далее.
