Я стажер, и у меня была возможность спроектировать и настроить «сервер приложений» для моей компании. В нем есть множество важных сценариев, и как часть моего процесса по его внедрению в производство я хочу задокументировать все, когда нужно передать управление кому-то, чтобы они понимали, как все работает.
Мы здесь немного старомодны, поэтому мы действительно хотим сохранить .docx (вероятно, будет преобразован в .pdf позже, но я работаю в Word) документации, поэтому я хотел спросить о документировании исходного кода. Там около 40 страниц, и короче говоря, когда я вставляю это в слово, это выглядит действительно уродливо.
Сейчас я вставляю его в WordPad, потому что он сохраняет более простой формат текста, сохраняя отступы и разрывы строк. Какой способ сохранить исходный код? Сами файлы были скопированы, но мне также нужен код на бумаге.
Спасибо.
Вам нужен текстовый редактор для исходного кода и проектной документации, а не текстовый редактор. Microsoft Word искажает ваш код «умными» кавычками и другими функциями набора текста.
Развертывание и настройку действительно нужно автоматизировать. Продемонстрируйте в действии: прокомментируйте сложные части ваших скриптов прямо и попросите другого человека просмотреть их для ясности.
Сосредоточьтесь на «почему» в отдельном проектном документе, в контексте дизайна высокого уровня и организации.
Передайте свою документацию той же системе контроля версий, которая управляет исходным кодом и скриптами. Наверное, сейчас git, но существуют и другие достойные варианты. Фиксация обычного текста позволяет использовать те же инструменты сравнения, слияния и обнаружения конфликтов, которые используются для исходного кода.
Существует множество языков разметки, которые могут отображать простой текст для экрана или печати. Markdown, вики, reStructuredText возможно, с красивыми выходами, генерируемыми Сфинкс, TeX, и так далее.