Thomas Schuiki thomasschuiki

"Documentation is a vital part of developing and using a computer-based system. In some commercial organizations, 20 to 40% of the total development effort goes into the documentation of the new system, recording how the new system is to work and how it was developed." Author, K.R. London

"...the four most important attributes about documentation include its content, maintenance, availability and use of examples."

What kind of documentation is there?

End user documentation
internal/systems documentation

Tips for better documentation

	-----BEGIN PGP PUBLIC KEY BLOCK-----

	mQINBGBst9UBEADHcyx7UyUnPDaQx2IXyuzym9eWcj52r/mVWnuLxY6BpDn41Y0R
	ISH8+sZsyErMwymgezldOqdL6R+d9z3k+uHSlISORjqbtJXhTQYgUqpyoBDJGL6r
	HLDjaa5NBOZO94phq3TxjUO6czGDsWMogGfEcxARod9XTNalUL3ZzBGRsoXsZL7J
	9wxoi8ljYvQZ081A/KIbKeopAHWmljAsOQvUdvw2LDs+WLStQMdBKpEi9j6vWiMi
	po1sEt+8sK/cfKuLGyfK5RVDi5tL13YbdTjNW1oYmN8/9zP9TH/3tJZ2C3hhGvk9
	lUoXDPeEko+KcprnyB1gLqSpkSdu58dnYf3TGRF4G3pfM90gWEK2SYqgI0WlCHqp
	Soqe2XTRrZ13bXzyNNgt1++A1wullXegfKjpgDHxbFB2Eut1c5HRU55h3RbJ4RiN
	DzOKjORZA6sNUv0p3ZG2YCuDaHvdxQERaDyFlKj9XCTx8gtQHeocDR4wd26Ny7ei

	# use /usr/bin/env to execute script in users environment
	#!/usr/bin/env bash

	# HEADER COMMENT
	#===================================================================
	# Title...............: testutility.sh
	# Description.........: A script that runs several tests.
	# Author..............: Max Mustermann
	# Date................: 03.09.2018
	# Usage...............: bash testutility.sh [options]

	# verify certificate of target host
	openssl s_client -verify 2 -connect dc1.myco.com:636

	# convert certificate file
	openssl x509 -inform der -in ca.example.com.cer -out ca.example.com.pem

	# on debian based systems, reload ca-certificates
	update-ca-certificates
	c_rehash


	# replace <word> with <replace> in filenames in current directory
	rename 's/<word>/<replace>/g' *
	# for rename -v >= 2.3
	rename <word> <replace> *

	# replace <word> with <replace> in filenames in all sub-directories
	rename 's/<word>/<replace>/g' **
	# for rename -v >= 2.3
	rename <word> <replace> **

	# find <word> only in files with extension
	grep -iHnR --include \*.ext "<word>" .

	# -i case-insensitive
	# -H human readable
	# -n display linenumber
	# -R recursive

 # replace <word> with <replace> in all files in current directory (creates backup files)
 sed -i.bak -- 's/<word>/<replace>/g' ./*
 # replace <word> with <replace> in certain files recursivly (creates backup files)
 find ./folder -type f -name "*.ext" -exec sed -i.bak -- 's/<word>/<replace>/g' {} +

	# just generate a exe
	cxfreeze --target-dir=bin main.py

	# optimize and compress output
	cxfreeze --target-dir=bin\v3 --target-name=mybin.exe -OO -c main.py

	# include missing modules
	cxfreeze --target-dir=bin --target-name=mybin.exe --include-modules=NAMES main.py

	# create new passwd with user1
	htpasswd -c /var/www/domain.com/public_html/.htpasswd user1

	# add user2 to passwd
	htpasswd /var/www/domain.com/public_html/.htpasswd user2

	# reference in htaccess
	AuthName "Restricted Area"
	AuthType Basic
	AuthUserFile /var/www/domain.com/htdocs/.mycustompasswordfile