Как да напишете софтуерна документация: 8 стъпки

Добър софтуерна документация - независимо дали е документ, съдържащ спецификацията на изискванията за програмисти или тестери, технически документ за вътрешни потребители, ръководството за използване на софтуер или програмата подкани за потребителите - помага на човек, работещ със софтуер, да разбере своите характерни характеристики и Функции. Следвайте съветите - как да пишете софтуерна документация за технически и крайни потребители.

Стъпка

Метод 1 от 2:

Писане на софтуерна документация за технически потребители.

един. Определят коя информация трябва да се спомене. Документи за софтуерните изисквания служат като справочник за дизайнерите на потребителски интерфейс, програмисти, които записват код и тестери, които проверяват дали софтуерът работи по следния начин. Точната информация зависи от самата програма, обаче, може да включва следното:

Ключови файлове в приложението. Това могат да бъдат файлове, създадени от екипа на разработчиците, бази данни, причинени по време на операцията на софтуера, и програмите за обслужване на трети лица.
Функции и подпрограми. Тук се посочва, че всяка функция и подпрограма прави, включително входни и изходни стойности.
Софтуерни променливи и постоянни и как те се използват в приложението.
Обща структура на програмата. За приложения, базирани на диск, вероятно ще се нуждаете от описание на индивидуалните блокове и програмните библиотеки, докато уеб приложенията ще се нуждаят от описание на страници, които използват файлове.

Изображение, озаглавено Пишете софтуерна документация Стъпка 2

2. Решете колко документация трябва да бъде в програмния код и колко трябва да бъдат разделени. Колкото повече се създава техническата документация в програмния код, толкова по-лесно ще актуализира този код като документация, свързана с различни версии на първоначалното приложение. Като минимум, документацията в програмния код трябва да обясни функциите, подпрограми, софтуерни константи и променливи.

Ако програмният код е доста дълъг, той може да бъде поставен като референтен файл, в който можете да търсите по ключови думи или указатели. Това ще бъде голям плюс за приложения, където логиката на програмата е разделена на много страници и включва помощни номера на файлове, както в някои уеб приложения.

Някои езици за програмиране, като Java или Net Framework (Visual Basic.Net, C #), имат свои собствени стандарти за документационен код. В такива случаи следвайте стандартните инструкции - колко документация трябва да бъде включена в програмния код.

Изображение, озаглавено Пишете софтуерна документация Стъпка 3

3. Изберете подходящ инструмент. До известна степен това се определя от езика, на който е написан код, било то C ++, C #, Visual Basic, Java или PHP - за всеки има собствен инструмент. В други случаи използваният инструмент се определя от вида на изискваната документация.

Текстов редактор "Microsoft Word" - инструмент за създаване на документация на отделни текстови файлове, която ще бъде проста и кратка. За дълги текстови файлове разработчиците на технически документи предпочитат да изберат програмата Adobe FrameMaker.

Съвет файловете за софтуерна кодове могат да бъдат написани с помощта на всеки инструмент, като RoboHelp, Help и Manual, Doc-To-Help, Madcap Flare или "Helplogix".

Метод 2 от 2:

Писане на софтуерна документация за крайните потребители

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

В никакъв случай програмната документация не трябва да замени лошия дизайн на интерфейса. Ако екранът на приложение изисква много обяснителна документация, по-добре е да промените дизайна на нещо по-интуитивно.

Изображение, озаглавено Пишете софтуерна документация стъпка 5

2. Разберете публиката, за която пишете документация. В повечето случаи потребителите на софтуер знаят малко за компютрите в допълнение към задачите на приложението. Има няколко начина за определяне на това как да координирате техните нужди с документация.

Погледнете професиите, притежавани от потенциалните ви потребители. Системният администратор вероятно ще бъде експерт в използването на софтуерни приложения, докато операторът за въвеждане на данни вероятно ще притежава заявлението, което той или в момента използва за въвеждане на данни.

Погледнете самите потребители. Въпреки че техните длъжности обикновено определят за какво се занимават хората, но има значителни различия в това как се използват някои позиции в тази организация. Провеждане на интервю с потенциалните потребители, можете да добавите вашето мнение - дали името на длъжността изпълни задълженията.

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

Определят задачите, които са необходими за тази работа и какви задачи трябва да се извършат, преди тези задачи да бъдат изпълнени.

Изображение, озаглавено Пишете софтуерна документация Стъпка 6

3. Определя съответния (и) формат на документацията. Софтуерната документация може да бъде структурирана в един от двата формата - справочник и инструкции за употреба. Понякога е по-добре да изберете смесена версия на тези два формата.

Референтният справочник е предназначен да обясни инструментите на софтуера (бутони, таблици, поле и диалоговия панел) и как работи този инструментариум. Много бързи файлове са написани в този формат, а контекстните подкани помагат да покажете желаната тема, след като потребителят кликне върху бутона "Помощ" на желания екран.

Инструкции за употреба обяснява как да използвате софтуер за извършване на конкретна задача. Инструкцията за употреба често има печатник или PDF формат, въпреки че някои подкани включват теми за това как да изпълняват конкретна задача. (Тези референтни теми обикновено не са контекстуални, въпреки че могат да бъдат хипервръзки) инструкцията за употреба често има формата на справочник с описание на задача и инструкции стъпка по стъпка.

Изображение, озаглавено Пишете софтуерна документация Стъпка 7

4. Решете кой формат (формати) трябва да бъде. Софтуерната документация за крайните потребители може да бъде един или повече формати: Ръководство за печат, документи в PDF формат, файлове на съвет или онлайн помощ. Всеки от тези формати е създаден, за да покаже на потребителя как да използва всяка програма функция - да бъде кратък преглед или ръководство. Както в случай на бързи файлове и онлайн помощ, документацията може да има демонстрационен видео или текст със снимки.

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

Изображение, озаглавено Пишете софтуерна документация Стъпка 8

пет. Изберете подходящ инструмент за създаване на документация. Print Guides или PDF формат могат да бъдат написани в текстови редактори като "Word" или "FrameMaker", в зависимост от дължината и сложността на ръководството. Съвет файловете могат да бъдат написани с помощта на такива инструменти за разработка като "Robohelp", "Help и Manual", "Doc-to-help", "Flare", "Helplogix" или "Healserver".

Съвети

Текстът трябва да бъде лесен за четене, снимките трябва да бъдат разположени възможно най-близо до текста, към който принадлежат. Плъзнете документацията за раздели и логически теми. Всяка част или тема трябва да засяга определен въпрос, независимо дали е една програма или задача. Свързани въпроси трябва да бъдат посочени "за гледане и" с хипервръзка, ако е необходимо.
Всички инструменти за създаване на изброени по-горе документи могат да бъдат допълнени от програмата на екрана, като например Snagit, ако документацията изисква определен брой скрийншоти. Както и при другата документация, скрийншотите трябва да обяснят как работи софтуерът, а не да подвежда потребителя.
Важно е и тонът на документацията за писане, особено ако е написано за крайните потребители. Използвайте второто лице "You", вместо на трета страна "потребители".

От какво имаш нужда

Инструмент за писане на документация / дебюла
Инструмент за създаване на скрийншоти