15 solid tips on producing good documentation

Documentation has been very dear for me for a long time. The usefulness and importance of documenting is just so immerse! In this post I’ll take a chop on some of my thoughts on documenting.

  1. Keep it simple stupid. Documentation should be brief and to the point. Do your best in having economy of words, don’t spend them easily. Simple bulletpoints goes a far way! Use simple langugage and short sentences.
  2. Use English when writing! Even if you are an entirely non-English shop, write in English still. You never know when you are going to expand into neighbouring countries that may require you to share information in English. Also, I am sure you’ve had to work with a consultant one-time or another, where the consultant is only English speaking. And no, Google Translate won’t cut it.
  3. Screenshots or video are not a preferred way to document. They can compliment existing documentation, but should not be your only documentation.
  4. Don’t create documentation using only copy/paste from whitepapers or the like. Only do this if it is a 100% fit for purpose. Instead consider linking and referencing the material rather than copy it.
  5. Capture the essence of the information you are creating. Make it as simple as possible to read and understand the documentation. “Economy of Words” gets you a long way!
  6. Don’t include passwords in the documentation. Sensitive information is usually OK as the documentation should be behind access restrictions, however passwords are not. Passwords should be changed regulary, so instead of storing them in e.g. the wiki, store them in a password manager. I’ve written a blog about using password managers here.
  7. Documentation should be a part of business requirements. Don’t let systems, services or other things go live without having at least a simple documentation readily available. It shouldn’t take long to set up some simple documentation scaffolding and adding some information to it.
  8. Keep the documentation platform highly available, good performance and ease of use. A wiki, i.e. Mediawiki, is excellent for this. If you make documentation tedious and hard, it won’t be used. Trust me on this!
  9. Knowledge is power; hence many will avoid documenting to keep them valuable to the business. Don’t be this guy! First of all, you will quickly be noticed using this strategy, second, any thriving business will be looking to keep good employees. Documenting, and thus helping build a healthy organisation, will ensure you are sticking around for the end game.
  10. Don’t get stuck doing the same repeatable tasks over and over again. Create good procedures and next time, someone else might be doing your tasks. Spreading the knowledge will allow you to move on to more challenging tasks. Having solid documents may even allow you to easily out-source your work load to the servicedesk.
  11. Keep your documentation solution always ready. If it’s a notepad or a wiki, always have it signed in and ready for you to type in. The moment it is not trivial to document, you are most likely going to skip it. Make it as easy as possible for yourself to create notes.
  12. Do not wait until the last minute to write documentation. You will forget what you did! Instead, write it as you work. If you did something wrong with your setup, requiring you to redo parts of the documentation, that is fine. Just go back and edit the step which you had to change.
  13. Update the documentation, don’t let it go stale. Stale documentation is bad, and wrong documentation is even worse. Ensure that it is simple and easy to update documents.
  14. Not everyone is an author. However, you still need to write something. Just remember to keep your information easily readable and understandable. Point back to point 1, KISS.
  15. Avoid repetition. Duplicate information is a no-go. It is a hassle to update information multiple places, instead use your documention platforms features for inclusion of duplicate information from one master source.

Got some tips of your own? Leave it in the comments. Thanks for reading!

How to Password Reset

A lot of companies and organisations does not do password resets properly today. Here is a recipe on how to do it securely.

  1. User enters the login page. This must be loaded over HTTPS.
  2. User clicks the “Forgot password” button. The user must then supply something unique to the user, e.g. email or username.
  3. The backend system affirms the details submitted, but does not give away if the details are correct or not. The system simply states that “A password reset email has been sent to the user, if it exists”.
  4. The system sends an email to the email address behind the username . The email must contain the following:
    • Who ordered the email? IP address and the country behind that IP is useful information.
    • Time and date the reset was ordered.
    • Some information regarding the password reset function and a notification to ignore this email, if it was not them who ordered it.
    • A unique link back to the system where the password reset in itself is done. The link needs to have the following properties:
      • It should contain a high entropy unique key, e.g. a long and strong unique key. This key should be as good as impossible to guess.
      • A fixed time the key is valid, e.g. the link only allows password resret if it is clicked within 15-30 minutes.
      • The link must be loaded over HTTPS.
    • Inform on the duration the link is active and that it is a one-time use link.
  5. The user is then taken to a form where he can enter his new password.
  6. Send a new email to the user, notifying that his password was in fact changed.

LinkedIn Phish – Investment Proposal

Today I received the following message from a LinkedIn contact:


I hope all is well with you, please review this recommendation for an investment opportunity which am considering a partnership with you if you’re interested. I hope that the reasons for this investment, which are alluded to in more details in the enclosed document( http://parkingticketing.co.uk/libraries/investment/dbnew ), will make you consider this alliance positively.

I hope you you will reply soon. With best wishes,

Warm Regards,


I think this looked wierd, so I opened the site in a safe browser and explored a little. It turned out it was definitely a phish. The landing page looks thrustworthy:



The bad guys left a mistake though at http://parkingticketing.co.uk/libraries/investment/dbnew.zip . This zip file contains some simple scripts that sends all credentials submitted to the following email address: willysnows1952@gmail.com .The script then redirects you to this PDF: http://www.morganstanley.com/about/press/ip-poll-national-432013.pdf

I’ve sent an email to ParkingTicketing.co.uk to notify them about this phish.

SQL Join types explained with 1 picture

Venn diagrams are often over-used, however in this scenario it is a truly perfect fit for explaining SQL Joins.

If you ever wonder how a join works or which join you should use, take a look at this picture:

SQL Joins


[important]Credits to CL Moffatt for creating this picture: http://www.codeproject.com/Articles/33052/Visual-Representation-of-SQL-Joins[/important]

Password managers, why isn’t everyone using them already?

I am very surprised that people, still today, do not have sufficient knowledge of the existence of password managers. They make IT life so much easier for us!

Think about what us security people are preaching: “You need to have a unique password for every single account”. That’s pretty rough demand, especially if the password is supposed to be truly unique, not just a spin-off of a master password. Having this in mind, here is a statement I find it hard to dispute:

[important]It is impossible to remember all your different usernames and password combinations. Additionally it is impossible to create passwords that adhere to all the different policies, that all the different systems have in place. [/important]

Windows Live only support 16 characters. What if your password is 20 characters, then you have to keep track of another variance of your password. Additionally, some systems limit the use of special characters, or they force you to, in some way or another, use a different password. If you are like me, you are registered on so many systems all over the internet, that you wont be able to keep track off all your passwords, let alone your usernames.

Not just passwords, usernames too

Guys, girls and foreign species; listen! I currently have 144 DIFFERENT ACCOUNTS! For these accounts I have 20-30 different usernames. Yes, 20-30 different usernames! How is ANYONE suppose to remember all that information unless you are Sheldon Cooper from Big Bang Theory? Keep in mind, you are supposed to have a unique password per service as well. This means that just a slight variation of your master password is, in theory, not good enough, as an attacker could very well crack it by learning your algorithm for varying your password. The attacker already has your password in clear-text, so he can easily read it from one of hte compromised sites you have registered at. It is not good enough to only have variance protect against automated bot attacks.

If we are going to practice what we preach, then there is no other solution than have a password manager as far as I know. Mind you, this password manager may very well be a notebook (analog paper) instead of an IT system. This to make sure your mom, grandma and others, not so techie, can also keep up with the requirements today. A notebook? Really? Really!! What are you the most worried about? A burglar stealing your password notebook, or a thief online stealing your identity?

keep calm and carry

A take on password managers

So what is a Password Managers? Well, first of all a disclaimer: I am in no way, shape or form, involved in the development, sales or companies who own Password Managers. I just find them extremely useful, hence me sharing my thoughts with you.

Password Managers store all your accounts information in a secure and good way. The only thing you have to remember is one master password in order to unlock your little database.The database lets you easy search and then copy both username and password for the account you need. It also helps you easily generate unique and secure passwords. Lending a quote from the article linked beneath:

Password managers are a simple
way to securely store all of your
different passwords for each of
your different account

So the next time you type in your password, I’ll ask you “why you bother??”, instead use a password manager. It is easier, safer and quicker!

The password manager I use is called KeePass. I use this for both personal and business use. We also use this on the IT-Operations team. I have my personal KeePass database also connected on my phone (via Dropbox), so I can easily use the logins in my manager from my phone. I have also stored my pincodes for access control cards, cell phone pins and more in this password manager. Everything I have is safely stored in an encrypted database, protected by one, strong and unique password.

Keepass can be downloaded from here: http://keepass.info/
For further reading I suggest looking at SANS Securing The Human newsletter Ouch. They wrote a newsletter specifically for Password Managers. Here it is in English:http://www.securingthehuman.org/newsletters/ouch/issues/OUCH-201310_en.pdf

You can also find it translated to other languages here:http://www.securingthehuman.org/resources/newsletters/ouch/2013

Good luck in implementing your new Password Manager. It really is easy to get started with, and there is little to no excuse not to have this today!

PS: Honorable mention to Lastpass. I have not used it myself, but many of my friends recommend it. Supposedly a very good password manager!