Documenting Source Code - Microsoft Word

Question

I'm an intern and I had the opportunity to design and configure an "application server" for my company. It has a variety of important scripts and as part of my process to put it into production I want to document everything for when control needs to be assigned to someone so they understand how everything works.

We're sort of old-fashioned here so we do want to keep a .docx (will likely be converted to .pdf later but I'm working in Word) of the documentation, so I wanted to ask about documenting source code. There's about 40~ pages of it and long-story short it just looks really ugly when I paste it into word.

Presently I'm pasting it into WordPad because it keeps a more simple format to the text while retaining indentation and linebreaks. What's the go-to method for keeping source code? The files themselves have all been backed up but I also need the code on paper.

Thanks.

A git repo. Nobody prints source code for archival purposes. — Michael Hampton, Jul 08 '19 at 16:57
@MichaelHampton Thanks! Unfortunately in my corp environment I can't use the git commandline tool due to firewalls but I'll keep this in mind for the future. — KuboMD, Jul 08 '19 at 17:39
Huh? Nothing about the git tool requires a firewall to be opened. — Michael Hampton, Jul 08 '19 at 18:17
@MichaelHampton Ah, you're right. I was confusing it with gitHub. Git works similarly offline/locally I suppose? — KuboMD, Jul 08 '19 at 18:32
Sweet! Will definitely give it a go. Thanks. Feel free to write an answer & I'll mark it. — KuboMD, Jul 08 '19 at 18:38

score 2 · Accepted Answer · answered Jul 09 '19 at 12:39

You want a plain text editor for source code and project documentation, not a word processor. Microsoft Word will mangle your code with "smart" quotes and other typesetting features.

Deploying and configuring a thing really should be automated. Show by doing: comment the tricky parts of your scripts inline and have another person review them for clarity.

Focus on the "why" in a separate design document, high level design and organization context.

Commit your documentation to the same version control system that manages source code and scripts. Probably git these days, but other decent options exist. Committing plain text allows the same diff, merge, and conflict detection tools used for source code.

Many markup languages exist that can render plain text for screen or print. Markdown, wiki, reStructuredText possibly with pretty outputs generated by Sphinx, TeX, and so on.

Documenting Source Code - Microsoft Word

1 Answers1