Sunday, 28 January 2018

You Should Absolutely Document Your Projects


Documentation. The bane of many a project. From lab reports, to field trip reports, to hackathon reports, to work reports - documentation in any shape or form is a nightmare for most. Unless we aren't the ones coming up with the documentation 😉.

While documenting a project may not cause one to leap up in joy, it is a crucial part of a project.



From a personal use level, documentation can prove to be useful. When you are working through a project, you are learning and solving problems. In the process, you possibly learn new ways of doing things and sometimes you could even come up with an ingenious way of accomplishing a task. In that moment you are an expert of sorts. Unfortunately, you could lead yourself to believe that if you did it once, you could always do it again. But memory has a way of failing us. With enough passage of time, we tend to forget the details of what was once a vivid memory. So a couple of months later you may revisit your old project to possibly look something up that you need for a new project you are working on. If you made really good documentation, you could save yourself hours of having to figure it all out again.

Chances are, as you were working on your project, you had to look up information about how to accomplish a particular task. You know what you just did? You looked up someone else's documentation. Now the documentation could have been a datasheet, which you kind of expect from a manufacturer (but not always, some have reason to be secretive), or even a tutorial. Whatever it is, it's something that made your life easier. In future, someone could totally be trying to do whatever it is your project entails and your documentation could be used as a guide to learn the necessary techniques. So why not be the person who passes it forward by making it just a little bit easier for the next person.

Documentation is also important if you want a community to grow. This one is important for school based communities that are run by students. The leadership in these kinds of communities is very volatile since leaders tend to come and go very quickly. The only way to build upon ideas is to make sure all projects run by the community are properly documented so all subsequent members have a blueprint upon which to build upon.

And last but not least, the most fun part about documentation is that you get to have a body of work that you can show off to people. You can be at a conference and be like, oh I am an engineer and I have worked on a bunch of projects. Oh, you want to see what I have done, boom DOCUMENTATION. Now give me that contract.

The best way to get better at documentation is simply by doing a lot of documentation. It's only through practice that you'll be able to get the right flow of everything. You'll over time figure out what is important to state and what isn't. What's the best way to document this and what isn't.

The other thing is to do your documentation as you work. Memories tend to fade with time and we also tend to get lazy the further we move away from a project. But if you make documentation a part of your development process, it makes it easier to finally come out with documentation that actually adds value to the world.

So as you start new projects in the future, always remember, it may not be fun to document your project, but it is extremely important. How else will the world know about the awesome things that you do?

Labels:

0 Comments:

Post a Comment

Subscribe to Post Comments [Atom]

Links to this post:

Create a Link

<< Home

THE OKELO: You Should Absolutely Document Your Projects

You Should Absolutely Document Your Projects


Documentation. The bane of many a project. From lab reports, to field trip reports, to hackathon reports, to work reports - documentation in any shape or form is a nightmare for most. Unless we aren't the ones coming up with the documentation 😉.

While documenting a project may not cause one to leap up in joy, it is a crucial part of a project.



From a personal use level, documentation can prove to be useful. When you are working through a project, you are learning and solving problems. In the process, you possibly learn new ways of doing things and sometimes you could even come up with an ingenious way of accomplishing a task. In that moment you are an expert of sorts. Unfortunately, you could lead yourself to believe that if you did it once, you could always do it again. But memory has a way of failing us. With enough passage of time, we tend to forget the details of what was once a vivid memory. So a couple of months later you may revisit your old project to possibly look something up that you need for a new project you are working on. If you made really good documentation, you could save yourself hours of having to figure it all out again.

Chances are, as you were working on your project, you had to look up information about how to accomplish a particular task. You know what you just did? You looked up someone else's documentation. Now the documentation could have been a datasheet, which you kind of expect from a manufacturer (but not always, some have reason to be secretive), or even a tutorial. Whatever it is, it's something that made your life easier. In future, someone could totally be trying to do whatever it is your project entails and your documentation could be used as a guide to learn the necessary techniques. So why not be the person who passes it forward by making it just a little bit easier for the next person.

Documentation is also important if you want a community to grow. This one is important for school based communities that are run by students. The leadership in these kinds of communities is very volatile since leaders tend to come and go very quickly. The only way to build upon ideas is to make sure all projects run by the community are properly documented so all subsequent members have a blueprint upon which to build upon.

And last but not least, the most fun part about documentation is that you get to have a body of work that you can show off to people. You can be at a conference and be like, oh I am an engineer and I have worked on a bunch of projects. Oh, you want to see what I have done, boom DOCUMENTATION. Now give me that contract.

The best way to get better at documentation is simply by doing a lot of documentation. It's only through practice that you'll be able to get the right flow of everything. You'll over time figure out what is important to state and what isn't. What's the best way to document this and what isn't.

The other thing is to do your documentation as you work. Memories tend to fade with time and we also tend to get lazy the further we move away from a project. But if you make documentation a part of your development process, it makes it easier to finally come out with documentation that actually adds value to the world.

So as you start new projects in the future, always remember, it may not be fun to document your project, but it is extremely important. How else will the world know about the awesome things that you do?

Labels: