Техническая документация: как написать

Люди,

Каков наилучший способ исследовать и представить технический документ? Я не имею в виду формат, обзор, разделы и т.д.

Я никогда не писал один - и мне интересно, должен ли белый документ быть очень универсальным (концептуальным) или конкретным (например, в пользу конкретного инструмента/методологии).

И если ваш ответ благоприятствует общему подходу, я хотел бы знать, как можно это исследовать. Лучше ли сосредоточиться на меньшем сценарии использования, начать с малого, использовать определенный инструмент/метод, получить хорошее понимание, а затем продолжить исследования и разработать широкоугольный взгляд на эту тему?

ОТВЕТЫ

Ответ 1

Да, попробуйте прочитать другие технические документы. Но не просто читайте белую бумагу. Читайте лучшие. Обычно вы можете определить, какая из них "лучше", указав, сколько раз была процитирована бумага. (Один веб-сайт, на который я иду для этого, cite seer и google ученого). Некоторые общие рекомендации:

  • Старайтесь быть прямо к делу, не бить вокруг куста.
  • Используйте свои акронимы последовательно.
  • Воспользуйтесь возможностью указать недостатки предыдущих методов, так как это показывает, что вы попытались просмотреть/изучить другие методы.
  • Техническая документация должна быть очень конкретной. Укажите, как работает ваш метод, точно укажите, как вы проводите эксперименты (чтобы другие могли повторять ваши эксперименты), точно укажите ваши результаты (много графиков было бы неплохо) и, наконец, завершите их в 40-60 слов или около того.
  • Акцент на вещи, которые являются новыми (материал, который вы предлагаете), и меньше на старых вещах (это было бы вашим фоном). Сделайте различие понятным.
  • Как правило, вы не включаете исходный код в свой документ. Если вам необходимо, опубликовано на веб-странице вместе со ссылками на ваш документ.

P/S: Мой совет немного предвзято относится к академической работе. Но я думаю, что он должен применяться в вашем случае.

Ответ 2

Цель белой бумаги обычно заключается в том, чтобы отстаивать определенную точку зрения или предлагать конкретное решение проблемы.

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

Ответ 3

Это звучит немного бесполезно, но белые документы приходят во всех формах, от очень специфических до очень общих. Определите, какова конечная цель. Вы пытаетесь что-то продать или описываете, как работает новый технический виджет, или описывают опыт? Кроме того, определить свою аудиторию - это бизнес, технический, домашний и т.д.

Взгляните на примеры - большинство крупных компаний (IBM и т.д.) имеют сотни на своем веб-сайте. Прочитайте несколько и посмотрите, что поражает вас как хорошие и плохие моменты.

Ответ 4

Мой 0.02:

Прочитайте пару и попытайтесь сделать mindmaps, пытаясь придумать, как они выглядят.

После того, как вы сделали этот анализ, вернитесь назад и выберите разделы, которые вам понадобятся. В частности, создайте ДРУГОЙ карту разума с вашей структурой документа.

Данные также являются важным способом передачи информации. Итак, подумайте о методах визуализации данных перед составлением диаграмм ваших данных.

Ответ 5

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

Например, документ, посвященный теме R + D или представленный в академических кругах, или предназначенный для обеспечения концептуального эскиза некоторой будущей работы, будет написан более пассивным голосом, почти Q + A. Обсуждение. Вы, вероятно, представите несколько идей и, возможно, будете их прокомментировать, не обязательно доведя окончательный вывод.

Техническая документация по конкретной технологии, для удобства клиентов по разъяснению или для иллюстрации или документирования какого-либо результата, будет очень твердой, фиксированной и иметь определенные выводы. Числа.

Единственное, что вы можете сказать в целом, это то, что процесс работает от неопределенного → конкретного.