Документацията е съществена част от цикъла на разработка на софтуер. Той обяснява как да използвате софтуера и може да включва ръководства за потребителя, препратки към API, инструкции за инсталиране и бележки за изданието.
Автоматизирането на вашата документация е най-новата тенденция, тъй като може да ви помогне да спестите време, да намалите грешките и да осигурите последователност. Поддържането на вашата документация актуална и достъпна за всички заинтересовани страни улеснява сътрудничеството и непрекъснатото подобряване.
Документите като код е подход за автоматизация на документацията, който третира техническата документация като код.
Какво представляват документите като код?
Документите като код е философия за разработка на софтуер, която разглежда техническата документация като форма на код. Това предполага, че трябва да третирате документацията със същата строгост и процес като софтуерния код.
Идеята зад документите като код е документацията да се третира като първокласен артефакт от процеса на разработка, като се интегрира с жизнения цикъл на софтуера. Това означава третиране на документацията като неразделна част от кодовата база. Това означава да приложите към него същия контрол на версиите, непрекъсната интеграция и процеси на тестване, които правите към самия код.
В типична настройка на документи като код, вие пишете документацията в обикновени текстови файлове, обикновено в лек език за маркиране като Markdown, HTML или reStructuredText. След това го съхранявате в същото хранилище като изходния код. Това улеснява управлението и проследяването на промените в софтуера и документацията. Също така помага да се гарантира, че документацията е актуална с най-новата версия на кода.
Защо трябва да използвате Документи като код
Преди документите като код, документацията често се третира като отделна от кода, създадена с различни инструменти и процеси. Този по-свободен подход често водеше до остаряла документация и несъответствия с кода. Можете да се възползвате от няколко предимства, като приемете подхода на документите като код.
Подобрено сътрудничество
Документите като код позволяват сътрудничество между разработчици, технически писатели и други заинтересовани страни в процеса на разработка. Тъй като хранилището на кодове съдържа документацията, е лесно за различни страни да допринасят и да правят промени. Това помага да се гарантира, че документацията е точна, актуална и изчерпателна.
Подходът на сътрудничество към документацията помага да се гарантира, че тя включва цялата подходяща информация и че отразява точно софтуерната система, както е интерпретирана от всички страни.
Автоматизация на процесите и достъпност
Друго предимство на документите като код е, че позволява автоматизирани инструменти за генериране и публикуване на документация. Системата за изграждане може автоматично да генерира HTML или PDF версии на документацията от обикновени текстови файлове за публикуване в уебсайт или вътрешен портал за документация. Това прави документацията достъпна за повече заинтересовани страни.
Чрез автоматизиране на процеса на генериране и публикуване на документация, документите като код помагат за намаляване на времето и усилията, необходими за поддържане и публикуване на документацията. Това позволява на екипите за разработка да се съсредоточат върху подобряването на софтуера.
Контрол на версиите
Съхраняването на документация в същото хранилище на кодове като софтуера улеснява управлението и проследяването на промените и в двете.
Можеш да използваш системи за контрол на версиите като Git за проследяване на промените в документацията и връщане към предишни версии, ако е необходимо. Това помага да се гарантира, че документацията е точна и актуална и можете да проследявате и проверявате промените.
Типичните документи като работен процес на код
Типичният работен процес на документи като код включва писане, контрол на версиите, изграждане и хостинг:
Процесът на писане
Процесът на писане е първият етап от типичния работен процес на документи като код. Повечето технически писатели и инженерите по документация използват прост MarkDown, AsciiDoc или HTML. Те пишат документацията с помощта на инструменти като GitBook и Redocly, които осигуряват плавен процес.
Контрол на версиите за документация
Документацията се развива с развитието на кода. Ще ви е необходима сложна система за контрол на версиите като Git, Plastic SCM или Subversion, за да проследявате промените в документацията за по-лесно сътрудничество и проследяване на версиите.
Процесът на изграждане на документация
Процесът на изграждане включва обработка и компилиране на документацията в нейните формати за доставка. Те може да са HTML, PDF, EPUB или други. Процесът на документиране обикновено се улеснява с помощта на генератори на статични сайтове като Hugo и Jekyll.
Хостинг и разпространение на документация
Процесът на хостване или разпространение обикновено е последната стъпка от документите като процес на кодиране. Този процес гарантира, че документацията се доставя до крайния потребител и е достъпна за всички заинтересовани страни. Можете да използвате страници на GitHub или GitLab или персонализиран портал, за да разпространявате вашата документация в мрежата.
Можете да автоматизирате документацията на Go и Java с помощта на GoDoc и JavaDoc
Документацията като философия на кода революционизира писането и управлението на техническа документация.
Много езици за програмиране, включително Go и Java, предоставят инструменти за автоматизиране на документацията с помощта на коментари в кода. Go предоставя инструмента Godoc, а Java предоставя JavaDoc.