1

The Pains of Poor/Missing Documentation

There will be a time where you are attempting a new task, whether that is personally or professionally and you find yourself having to resort to the documentation of the product to get to the end goal, whether that be to put together a new piece of furniture, preparing an exquisite meal or bashing different bits of software together from different companies or more commonly the same company.

One thing that is common in all these scenarios is that if the documentation is completely missing then you are forced down the road where you take the “pot luck”/”educated” guess to get to the desired end result and sometimes that can lead to some hilarious results, especially if it is in relation to cooking or building furniture.

In personal experience this has been most common with second-hand furniture and this is because there are few people that keep their assembly instructions once the furniture has been assembled. I think this is due to the “I’ll never need to take this apart and build this again” thoughts that we like to have.

This mentality as it were is what is rather similar in the IT world as well and it is because of this that we have seen lots of undocumented software features. Anyone who has worked with the SharePoint Object Models in much depth will be more than familiar with idea of missing documentation.

 

In the IT world this is something that we have all understood and realised was an issue and at some point in our careers we’ve all been on the receiving end of a lack of documentation or poor documentation and when it happens we’ve either had to turn to technical forums or write it ourselves.

Over the years this has started to get better and I for one am glad to see the initiatives that Technology Organisations are taking to start Open Sourcing product documentation. A number of Teams at Microsoft are doing this now via Github and this to me reinforces the need for all IT Pro’s & Developers to understand how to use Github & the underlying Git software as a part of the core tools within their tool belts. In 3 years time I wouldn’t be surprised if other Source Control mechanisms like SVN & Mercurial have almost been fully replaced by Git. It says something that Microsoft have fully adopted Git into both the Hosted and On-Premises versions of TFS.

So if you read this blog and you haven’t learnt Git yet but are writing PowerShell – go and watch this Session that I did for the Mississippi PowerShell UserGroup as detailed in this previous post and read up on the “My Workflow With Git” Series starting with this post

 

We are at a good point in time where the people behind the products we love and use each day are listening to us in a much more open way than previously and over the coming weeks I’ll be updating the following site with all the Microsoft UserVoice / Connect links and in a nicer format than they currently are.

If you want to help and get involved then drop me a message and I’ll get you added to the Organisation to be able to add commits

One Comment

  1. Documentation is super important – if not for anyone else then just doing it for Future You pays off. It’s amazing how many times I’ve had to read my examples or read a function description to get a nuance that I’d forgotten about as I wrote the function more than a year ago.

Leave a Reply