0024: Documentation – most important thing. Most boring thing. I hate it. Don’t you?
Today’s note will be quite short. During last meeting with Andrzej, he pointed out that I don’t have documentation for the OLGAtherer. Of course, I said – because it’s so boring!
Yep. It is. But true is, that it’s also probably most important thing in the project. Without it we don’t even know what we want to do. If we don’t know what to do, we can’t know how to do it. That makes program lousy. I can cheat myself that my program will be good anyway, but without simple document that states what do I want OLGAtherer to do I can forget about it. Forgerabotyt. (Donnie Brasco rulez :)).
I’ve checked semi-professional documentation file and here is the table of contents from it:
Table of Contents
- 1 INTRODUCTION
- 1.1 Background & Purpose
- 1.2 Requirements
- 2 DESIGN
- 2.1 Use cases
- 2.1.1 Create a new project
- 2.1.2 Delete a project
- 2.2 Functional Design
- 2.2.1 Main window
- 2.2.2 Project Creation Wizard
- 2.2.3 Project replication
- 2.2.4 Deleting projects
- 3 TESTING
- 3.1 Projects list
- 3.2 Project creation and replication
- 3.3 Project deletion
- 4 RESTRICTIONS
- 4.1 Limitations
- 4.2 Dependencies
- 5 ISSUES
- 6 RELEASE STRUCTURE
- APPENDIX A COMMUNICATION
As you can imagine, I need to reflect at least second paragraph of the first chapter (Requirements) – I have to describe what I need OLGAtherer to do. Background isn’t vital, but would be nice, I think. Problem is that I have no willingness to write this whole thing, so probably I do only most important points.
OK, so one paragraph since now. Design is, I think, critical here. First paragraph contains use cases as a tables where user actions are described. I think that better would be here sequential diagram (something like in PLC programming – you know, I’m Industrial Process Engineer by profession :)), but anything will be OK – content is vital here, not form that it’s depicted.
Paragraph 2.2.1 contain windows design and describes purposes of all controls – it’s nice to have, too.
Chapter 3 describes tests that should be done. In my case I think that I won’t create it now, because all tests could be created using use cases provided in the chapter 2. Maybe I’m wrong now, but time will show – if so, I will just try to describe tests too.
Chapter 4 – restrictions, limitations and dependencies, chapter 5: issues – I don’t know nothing about it at the moment.
Appendix – Communication – my email address will do the trick 🙂
That’s it. Why I wrote this post? Because probably in a few next days I will try to write skeleton of the documentation, and this may absorb me completely, so code and blog won’t be updated for a while. I know also that this is only my private diary (no one probably reads it), so I treat this blog like it, and note things to do. So don’t be surprise if you see posts like this 🙂
Best regards, me.