Without going too far off track I am a one man development team in a two man IT department for a small company that manufactures and sells their own brand of goods.
I look after approximately 17 projects, where I am expected to change things as needed or patch bugs etc.
There have been some changes lately in staffing and it’s opened up a window of opportunity to do things that previous developers couldn’t, one of those things being writing technical documentation and specs.
Whilst the documentation side of things doesn’t worry me too much, I would like to know the best way to write a spec. What I am really looking for is a way of dumbing down the content so that the “customer” understands what I am going to do to meet their requirements.
Currently I just get asked to do things, usually off of the back of an email chain, or in an IT ticket etc. I typically trawl through the existing code to see where I will need to make changes, write a couple of abstract pieces of code, write the tests to do what I think the user wants and then basically code it all up test it locally then deploy live. (Though lately I have been making development copies of systems, so that users can approve the work before a go live).
I would like to know two things really. The first being, how do you write a software spec which details what you intend to do to achieve the desired outcome, with out dropping technical jargon all over the place? And lastly, if you do this, how do you currently structure the documents?
On the last last point I am currently writing an overview with details on what I am changing, why and how. The going into a section of proposed changes detailing what classes I intend to write, what methods the have another section on the functional aspects i.e how the changes I’ve proposed will work and how that achieves the outcomes requested and then lastly a list of all the changes I will make (though I think that probably belongs to a technical change documentation as opposed to the spec).
Apologies for the rather length of the post!