Nice article about traditional documentation ...
I find a lot of interest among developers in documentation they can update themselves, in a more real-time fashion. Along with this, there is value for the 'curator' role, a librarian / editor who organizes, edits, prunes the documentation tree.
Atlassian is one vendor we work with whose public wiki is a nice example of crowd-sourced documentation combined with other types of information. Open source projects often have similar documentation sites.
Any thoughts on how that fits into the pardigm you are describing?
Discussion on:
View:
Show:
Almost no one views creating documentation as their job, they see it as an annoying fact of life, like getting the tires on your car rotated. If there is no one over their shoulder reminding them to do it, they start to forget really quickly. The more work that a tool makes it to do it (for example, leaving the development environment to open a document, wiki editor, etc.), the less likely it is to be used, unfortunately. While I haven't used the Atlassian tool directly and can't comment on it, I know from just about every app I've ever written, the more effort (even if it's "just five seconds more") it takes to get something done, the less likely it will be to get done unless it produces huge, obvious benefits, or the process makes it unavoidable (like "can't check into source control without do it it" or something).
J.Ja
J.Ja
I find your list lacking as it doesn't outline anything required for a any proper QA regimen.
A QA plan. Who does what, what other docs are needed, what testing will be done, by who. Who checks that everything is being done to the plan.
Number one would be a document outlining the basic premise of the software, what it will do, scope, users and a rough estimate of time and cots against estimated revenue. Cost benefit analysis, should we even try to do this.
A document showing you thought about what level of quality assurance that you need to use to build a quality product.
You would then set out requirements. These may not all be known at this point but try to get as many as you can down.
Then a design. What parts of your program, the interfaces between them. What does what, how will it look, what inputs and what outputs.
A programmers handbook, info programmers need, what tools and processes to be used.
Then code and document your code. Updating the previous documents as you go. And making unit test code as well. Unit tests should never be in the same file as your code that is being tested and a build of your software should not rely on unit test code. Unit tests should be repeatable and output something that can be compared for regression testing.
Software configuration management and change management. Change management is work flow for changes. How this is handled should be documented and your change management software should capture this information for auditing.
Test plans.
test reports of some type.
Integration testing, automated if possible and output in a way that it can be checked and compared to previous integration test runs.
User manuals.
Maintenance and update plans.
I write software for nuclear reactors. We have to be able to prove we make our software in a quality way and show that the software is tested, tested properly and will work without error.
We have ISO standards for software quality assurance and software quality processes. Your requirements may not require all of the above but even if you simplify and put some of those documents together you should be doing the all of the above in some manner.
Then not only do you know your software does what it's supposed to but that it also doesn't do what it's not supposed to. And also when someone like me comes to you and wants to use your software I can check that it's done in a quality manner and I can defend using it because believe me I have to defend using the software I do.
if you do all of these things then not only does your software have a better chance of working but then a lot of people in business and government will be able to use your software.
A QA plan. Who does what, what other docs are needed, what testing will be done, by who. Who checks that everything is being done to the plan.
Number one would be a document outlining the basic premise of the software, what it will do, scope, users and a rough estimate of time and cots against estimated revenue. Cost benefit analysis, should we even try to do this.
A document showing you thought about what level of quality assurance that you need to use to build a quality product.
You would then set out requirements. These may not all be known at this point but try to get as many as you can down.
Then a design. What parts of your program, the interfaces between them. What does what, how will it look, what inputs and what outputs.
A programmers handbook, info programmers need, what tools and processes to be used.
Then code and document your code. Updating the previous documents as you go. And making unit test code as well. Unit tests should never be in the same file as your code that is being tested and a build of your software should not rely on unit test code. Unit tests should be repeatable and output something that can be compared for regression testing.
Software configuration management and change management. Change management is work flow for changes. How this is handled should be documented and your change management software should capture this information for auditing.
Test plans.
test reports of some type.
Integration testing, automated if possible and output in a way that it can be checked and compared to previous integration test runs.
User manuals.
Maintenance and update plans.
I write software for nuclear reactors. We have to be able to prove we make our software in a quality way and show that the software is tested, tested properly and will work without error.
We have ISO standards for software quality assurance and software quality processes. Your requirements may not require all of the above but even if you simplify and put some of those documents together you should be doing the all of the above in some manner.
Then not only do you know your software does what it's supposed to but that it also doesn't do what it's not supposed to. And also when someone like me comes to you and wants to use your software I can check that it's done in a quality manner and I can defend using it because believe me I have to defend using the software I do.
if you do all of these things then not only does your software have a better chance of working but then a lot of people in business and government will be able to use your software.
I have no idea if this comment is useful to anyone else, because I'm a novice who is working in a number of languages--formerly a senior technical writer, which also changes my perspective.
As I prepare for a programming task and start to flesh it out, I use the comments sections that I create on the fly for brainstorming, planning, and stream of consciousness reflections on where I'm going and why.
This means that my to-do list for any section is always right there in the code where I'm working on, as well as all of those crazy ideas that come out of nowhere and seem to get lost in the shuffle if you don't process them somehow.
When I'm done with a piece of code, I can remove all the crap, store ideas that are still relevant in another location, and edit what remains down to a fairly good description of why I'm doing certain things. Maybe if I was a more mature coder, this would all seem like a useless exercise, but for me, where I'm at, it makes the documentation part totally useful to me personally and ultimately creates better comment documentation for others.
When I worked at Fujitsu in the late 90s, I corresponded with Sun programmers about a module that they had for exporting javadocs into FrameMaker, and they responded by reworking the module to do exactly what I needed it to do. I did this because maintaining documentation in printed APIs and in code meant that I could never keep up. The new system allowed me to write once, publish in two places.
So I have a lot of respect for those comment sections.
As I prepare for a programming task and start to flesh it out, I use the comments sections that I create on the fly for brainstorming, planning, and stream of consciousness reflections on where I'm going and why.
This means that my to-do list for any section is always right there in the code where I'm working on, as well as all of those crazy ideas that come out of nowhere and seem to get lost in the shuffle if you don't process them somehow.
When I'm done with a piece of code, I can remove all the crap, store ideas that are still relevant in another location, and edit what remains down to a fairly good description of why I'm doing certain things. Maybe if I was a more mature coder, this would all seem like a useless exercise, but for me, where I'm at, it makes the documentation part totally useful to me personally and ultimately creates better comment documentation for others.
When I worked at Fujitsu in the late 90s, I corresponded with Sun programmers about a module that they had for exporting javadocs into FrameMaker, and they responded by reworking the module to do exactly what I needed it to do. I did this because maintaining documentation in printed APIs and in code meant that I could never keep up. The new system allowed me to write once, publish in two places.
So I have a lot of respect for those comment sections.
... like Visual Studio, comments that start with "TODO" are treated specially and added to a task list, you might find that helpful with your workflow.
J.Ja
J.Ja
- Keyboard Shortcuts:
- Prev
- Next
- Toggle
