Добрата софтуерна документация, независимо дали става дума за спецификация за програмисти и тестери, технически документи за вътрешни потребители или ръководства и помощни файлове за крайни потребители, ще помогне на потребителите да разберат характеристиките и функциите на софтуера. Добрата документация е конкретна, ясна и уместна документация с цялата информация, от която се нуждае потребителят. Тази статия ще ви насочи да пишете софтуерна документация за технически и крайни потребители.
Стъпка
Метод 1 от 2: Писане на софтуерна документация за технически потребители
Стъпка 1. Знайте каква информация да включите
Спецификационният документ се използва като справочно ръководство за дизайнери на интерфейси, програмисти, които пишат код, и тестери, които проверяват производителността на софтуера. Информацията, която трябва да бъде включена, ще зависи от създаваната програма, но може да включва следното:
- Важни файлове в приложението, като файлове, създадени от екипа за разработка, бази данни, достъпни по време на работа на програмата, и приложения на трети страни.
- Функции и подпрограми, включително обяснение за използването на функцията/подпрограма, входни и изходни стойности.
- Променливи и константи на програмата и как се използват.
- Обща структура на програмата. За програми, базирани на устройства, може да се наложи да опишете всеки модул и библиотека. Или, ако пишете ръководство за уеб-базирана програма, може да се наложи да обясните кои файлове използва всяка страница.
Стъпка 2. Решете какво ниво на документация трябва да присъства и да бъде отделяно от програмния код
Колкото повече техническа документация е включена в програмния код, толкова по -лесно ще бъде да я актуализирате и поддържате, както и да обяснявате различните версии на програмата. Като минимум документацията в програмния код трябва да включва използването на функции, подпрограми, променливи и константи.
- Ако вашият изходен код е дълъг, можете да напишете документация в помощния файл, който след това може да бъде индексиран или търсен с определени ключови думи. Отделни файлове с документация са полезни, ако програмната логика е разделена на няколко страници и включва файлове за поддръжка, като например уеб приложение.
- Някои езици за програмиране (като Java, Visual Basic. NET или C#) имат свои собствени стандарти за документиране на кода. В такива случаи следвайте стандартната документация, която трябва да бъде включена в изходния код.
Стъпка 3. Изберете подходящия инструмент за документиране
В някои случаи инструментът за документиране се определя от използвания език за програмиране. Езиците C ++, C#, Visual Basic, Java, PHP и други имат свои собствени инструменти за документиране. Ако обаче не, използваните инструменти ще зависят от необходимата документация.
- Текстов процесор като Microsoft Word е подходящ за създаване на текстови файлове на документи, стига документацията да е кратка и проста. За да създадат дълга документация със сложен текст, повечето технически писатели избират специализиран инструмент за документация, като Adobe FrameMaker.
- Помощните файлове за документиране на изходния код могат да бъдат създадени с програма за генериране на файлове за поддръжка, като RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare или HelpLogix.
Метод 2 от 2: Писане на софтуерна документация за крайни потребители
Стъпка 1. Запознайте се с бизнес причините за създаването на ръководството
Въпреки че основната причина за софтуерната документация е да помогне на потребителите да разберат как да използват приложението, има няколко други причини, които могат да стоят в основата на създаването на документация, като например подпомагане на маркетинговия отдел да продаде приложението, подобряване на имиджа на компанията и намаляване на техническата поддръжка разходи. В някои случаи се изисква документация, за да съответства на разпоредбите или други законови изисквания.
Документацията обаче не е добър заместител на интерфейс. Ако дадено приложение изисква много документация за работа, то трябва да бъде проектирано така, че да бъде по -интуитивно
Стъпка 2. Познайте целевата аудитория на документацията
По принцип потребителите на софтуер имат ограничени компютърни познания извън приложенията, използвани от тях. Има няколко начина да се задоволят техните нужди от документация:
- Обърнете внимание на заглавието на потребителя на софтуера. Например системният администратор обикновено разбира различни компютърни приложения, докато секретарят знае само приложенията, които използва за въвеждане на данни.
- Обърнете внимание на потребителите на софтуер. Въпреки че техните позиции обикновено са съвместими с изпълняваните задачи, тези позиции могат да имат различно натоварване в зависимост от мястото на дейност. Като интервюирате потенциални потребители, можете да разберете дали вашата оценка за длъжността им е правилна.
- Обърнете внимание на съществуващата документация. Документацията и спецификациите за функционалността на софтуера могат да покажат какво трябва да знаят потребителите, за да ги използват. Имайте предвид обаче, че потребителите може да не се интересуват от познаването на „вътрешностите“на програмата.
- Знайте какво е необходимо, за да завършите задача и какво е необходимо, преди да можете да я изпълните.
Стъпка 3. Определете подходящия формат за документацията
Софтуерната документация може да бъде подредена в 1 или 2 формата, а именно справочници и ръководства. Понякога комбинирането на двата формата е добро решение.
- Референтните формати се използват за описване на всички софтуерни функции, като бутони, раздели, полета и диалогови прозорци, и как работят. Някои помощни файлове са написани в този формат, особено тези, които са чувствителни към контекста. Когато потребителят кликне върху Помощ в определен екран, той ще получи съответната тема.
- Ръчният формат се използва за обяснение как да направите нещо със софтуера. Ръководствата обикновено са в печатни или PDF формати, въпреки че някои помощни страници съдържат и инструкции как да се правят определени неща. (По принцип ръчните формати не са чувствителни към контекста, но могат да бъдат свързани от контекстно чувствителни теми). Наръчниците обикновено са под формата на ръководство, с обобщение на задачите, които трябва да бъдат изпълнени в описание и ръководство, форматирано на стъпки.
Стъпка 4. Определете вида на документацията
Софтуерната документация за потребителите може да бъде опакована в един или повече от следните формати: отпечатани ръководства, PDF файлове, помощни файлове или онлайн помощ. Всеки вид документация е създаден, за да ви покаже как да използвате функциите на софтуера, независимо дали е ръководство или урок. Онлайн документацията и помощните страници могат също да включват демонстрационни видеоклипове, текст и статични изображения.
Онлайн файловете за помощ и поддръжка трябва да се индексират и да се търсят с помощта на ключови думи, така че потребителите да могат бързо да намерят необходимата им информация. Въпреки че приложението за генериране на помощни файлове може да създаде индекс автоматично, все пак се препоръчва ръчно да създадете индекс, използвайки често търсени ключови думи
Стъпка 5. Изберете подходящия инструмент за документиране
Отпечатани ръководства или PDF файлове могат да бъдат създадени с програма за текстообработка като Word или усъвършенстван текстов редактор като FrameMaker, в зависимост от дължината и сложността на файла. Помощните файлове могат да бъдат записани с програма за създаване на помощни файлове, като RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix или HelpServer.
Съвети
- Текстът на документацията на програмата трябва да бъде структуриран по такъв начин, че да е лесен за четене. Поставете изображението възможно най -близо до подходящия текст. Разделете документацията по раздели и теми логически. Всеки раздел или тема трябва да описва конкретен проблем, както задачи, така и функции на програмата. Свързаните проблеми могат да бъдат обяснени с връзки или списъци с препоръки.
- Всеки от инструментите за документация, описани в тази статия, може да бъде допълнен от програма за създаване на екранни снимки, като SnagIt, ако вашата документация изисква множество екранни снимки. Както всяка друга документация, трябва да включите и екранни снимки, за да обясните как работи приложението, вместо да „примамвате“потребителя.
- Обръщането на внимание на стила е много важно, особено ако пишете софтуерна документация за крайните потребители. Обърнете се към потребителите с местоимението „вие“, вместо с „потребител“.
