Infrastructure from scratch. Part 1. Documentation

cartoon_unwrittenrulescartoon

I’m starting to lead DevOps diary about my first serious project. Probably diary records must have a special and distinguish format. Hence I’d like to share these thoughts:

  • Why described subfield is important
  • What tool I chose and why
  • What’s done
  • Advices
  • Random thoughts

Wow, I clearly explained what I want from my crazy wish to share experience. Now let’s go on!

Documentation system won’t be on the first place in any IT project. But it’s easy to deploy and quickly to introduce your teammates. Unfortunately it takes a long time to force anybody document things they’ve done. So, because of these opposite facts I started my project work from documentation.

Why is it important?


Trying to explained that, I looked for any smart quote about legacy. I’ve found this one.

“Carve your name on hearts, not tombstones. A legacy is etched into the minds of others and the stories they share about you.”

― Shannon L. Alder

Oh, no! It doesn’t work in IT! You forget almost all you did 2 weeks ago. And you don’t need to keep in mind any change you’ve done at all. Your brain should concentrate on current issues. If you will try to keep in mind everything – you can forget many other things your work should not overwrite.  It could be the name of your grandmother, the mascot of your favorite sport team and whatever else.

Also there is a problem of team changes. The more your project rises up – the more legacy and information you have about it. When new teammate is hired, you’re trying to introduce him to project structure. Anyway you can’t explain all details – something is forgotten, something seems unimportant, but mistakenly.

For all described issues documentation is going to be your best friend. Keep your thoughts and issue reports, schemes and bug solutions. Afterwards you will make your life smooth and life of your collaborators generally.

Tools


I picked up MediaWiki to implement centralized documents storage. The benefits:

1. Well-readable and familiar document format. everybody got at least hundreds of articles on Wikipedia, so it’s not difficult to tell others what is it

2. Easy to set up. Install LAMP – unarchive source – create database – push a couple of buttons on web – and you’ve done!

3. Perfect to improve. There are plenty of useful MediaWiki extensions. Highlight your code? Make dynamic pages? Build spoilers? Got it!

4. Easy to maintain. I don’t remember that MediaWiki engine bumped up with many bugs and denials. Also hardware issue solves pretty straightwofward. One server with 512MB memory is really enough to store Wiki. Your webserver won’t take too much connections, becuase there won’t be nobody but your team.

Also it’s plain to secure and restrict, simply to change. I can list its advantages up to couple of dozens items. Let’s stop on it.

Also we have Jira to assign and track project issues. It was deployed before my arrival. So, you all know what it is and why it’s so popular. Won’t stop on it, just saying that local Jira installation makes as simply as possible.

Oh, pardon me. I almost forgot about schemes. Schemes are brilliant to keep your infrastructure visible and understandable. Service scheme allows to learn the project to others and remind you existed pitfalls. How components iteract with each other, what’s the input data and what’s the output. Network schemes are useful at all! I don’t know how to debug network outages and problems when you don’t have a clue what’s is the cable system layout.

I use draw.io to write my own schemes. They have an outstanding AWS template and much more IT stuff else.

What’s done?


At first I installed and configured MediaWiki on t2.nano AWS EC2 instance. The components: Apache, PHP5, ImageMagick and PostgreSQL. MySQL should be fine too. After I started to propagate documentation importance to our developers.

I severed Wiki platform on few categories: Development, Infrastructure and Management. Everybody can keep his own thoughts in suitable subfield. Additionally I saved there getting started articles and useful guides about formatting.

For myself I built Infrastructure category from few subcategories. There are Monitoring, Analysis, Services, Configuration and Bug Store. Each of them handles special kind of tasks.

The best way to organize and maintain Wki changes – set DynamicPageList tags on the main page. Thus your new articles will be automatically approved and clearly showed up.

Advices


1. Want to teach teammates to document thoughts – start from yourself! If someone hears requirements and doesn’t see anybody cares – he won’t care too. Documentation takes a time and has only far-sighted effect. So, have a patience to write every important change and thought. Later your teammates will recognize that it’s such useful and fill your storage.

2. Don’t keep your code in the plain text. Please! It’s hard to read and much harder to understand. Every documentation system has its own code highlight extension. For MediaWiki look at this.

3. Attract your stakeholders. With understandable documentation storage you can share your changes and suggestions with these guys. I guess there is more favorable way to poke them which saving your time and their time. You don’t need to tell them few hours every day the same things they forgot while documentation is here.

4. Don’t store your passwords there. Wiki is not for such sensitive data, forget it. Make anything else with password storage, like Keepass with CSV sharing.

Random thoughts


1. You don’t like MediaWiki? There is a lot of more open-source Wiki engines. You don’t like Wiki at all? Well, there is an alternative too.

2. When everybody is done with registration – close it for security reasons. You might not share your data with someone who logged in without approvement.

Hope you became interested to read my experiences. As soon as I will deal with other subfields – I will add new records to my diary. Thanks for attention!

Advertisements

One thought on “Infrastructure from scratch. Part 1. Documentation

  1. Pingback: Infrastructure from scratch. Part 1. Documentation — MyOpsBlog | SutoCom Solutions

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s