Silly Documentation Question
-
Hi, I have written a bit of Code to talk to bit of hardware. All good I now having to document it for the records, In the past I have worked on embedded and analogue test rigs which can be covered by a flowchart and a listing. This will not work for a Windows program there is too much going on compared to a PIC or Atmel. Is there a way of creating the asked for without going mad? It can't be too odd as I think there must be other companies who need this...
Its not a silly question to ask :) I would at least include: - source code documentation (Doxygen is your friend) - build instructions (which you tested on a clean machine) - description of the communication protocol between PC and the hardware - installation instructions (which you tested on a clean machine) - use instructions (e.g. command line arguments) - eventually an high-level flowchart of how the system operates The first two items are helpful when in the future, you or somebody else needs to do some work. The other are useful for the actual users and typically will be part of manual. Which I strongly advise you to make, if somebody else isn't doing. I have found that "have you read the manual ?" substantially decreases support effort :) A lot of work ? The first time yes, a few days at least, but then it is just minor edits to the documents. I use Doxygen for generating the documentation of the source code, of the language own tool if better. And Sphinx[^] for writing the manual and instructions.
-
Doxygen homepage[^] It's something you have to do as you write but when done it's a flexible doc system.
Definition of a burocrate; Delegate, Take Credit, shift blame. PartsBin an Electronics Part Organizer - Release Version 1.3.1 JaxCoder.com Latest Article: EventAggregator
My experience with Doxygen (my own direct use and how I have seen numerous co-workers use it) is that it is fine for the bottom level documentation. The reader will know all the details about the third argument to a given method, but without a clue about when, where and why that method is called at all. The protocol, both any line protocol and the protocol of interaction between methods in one module and the interaction between modules. In principle, you can add information about module and object interaction, line protocol specifications etc. My experience is that developers never get around to it Round Tuit[^]. Documenting the third parameter in a Doxygen comment is easy to do when you are editing the code; the higher level documentation is postponed until the next tuit delivery. (But sending the order has been postponed ... :-)). As long as the intermediate levels are documented well, from the top level, the main subsystems and their interactions, and then stepwise down to modules and objects, then the reader might as well dive right into the source code. When you understand the use of some component, you have no need for a Doxygen carbon copy of the details that you will find in the source code anyway. Too often, Doxygen 'documentation' is little more than a rephrasing of method header. Obviously, this very much depends on how developers use Doxygen. I am referring to what I have observed, not what you in theory can do with Doxygen. Equally important: This is certainly not Doxygen-specific. Give the same developers another documentation system that they can maintain as part of the code editing, and the result will be very much of the same. You see it everywhere, in almost all software and documentation available on internet: Method headers and parameters are documented; how these are intended to be used is often completely omitted. If there are some traces of it, it is often poorly written. (The best way learn the use of some library, server etc. is to search for some other open source code to see how they are using it!) So, my advice is: Forget about the source code documentation, at the method header and parameter level (with the exception of APIs exported to users outside your organization). Document it top-down, with focus on component interactions. If there are explicit protocols across a line, describe it, but document the protocol, not
-
My experience with Doxygen (my own direct use and how I have seen numerous co-workers use it) is that it is fine for the bottom level documentation. The reader will know all the details about the third argument to a given method, but without a clue about when, where and why that method is called at all. The protocol, both any line protocol and the protocol of interaction between methods in one module and the interaction between modules. In principle, you can add information about module and object interaction, line protocol specifications etc. My experience is that developers never get around to it Round Tuit[^]. Documenting the third parameter in a Doxygen comment is easy to do when you are editing the code; the higher level documentation is postponed until the next tuit delivery. (But sending the order has been postponed ... :-)). As long as the intermediate levels are documented well, from the top level, the main subsystems and their interactions, and then stepwise down to modules and objects, then the reader might as well dive right into the source code. When you understand the use of some component, you have no need for a Doxygen carbon copy of the details that you will find in the source code anyway. Too often, Doxygen 'documentation' is little more than a rephrasing of method header. Obviously, this very much depends on how developers use Doxygen. I am referring to what I have observed, not what you in theory can do with Doxygen. Equally important: This is certainly not Doxygen-specific. Give the same developers another documentation system that they can maintain as part of the code editing, and the result will be very much of the same. You see it everywhere, in almost all software and documentation available on internet: Method headers and parameters are documented; how these are intended to be used is often completely omitted. If there are some traces of it, it is often poorly written. (The best way learn the use of some library, server etc. is to search for some other open source code to see how they are using it!) So, my advice is: Forget about the source code documentation, at the method header and parameter level (with the exception of APIs exported to users outside your organization). Document it top-down, with focus on component interactions. If there are explicit protocols across a line, describe it, but document the protocol, not
The real problem is that there is not enough money or time in the budget for documenting and the programmer is usually to lazy to do it.
Definition of a burocrate; Delegate, Take Credit, shift blame. PartsBin an Electronics Part Organizer - Release Version 1.3.1 JaxCoder.com Latest Article: EventAggregator
-
The real problem is that there is not enough money or time in the budget for documenting and the programmer is usually to lazy to do it.
Definition of a burocrate; Delegate, Take Credit, shift blame. PartsBin an Electronics Part Organizer - Release Version 1.3.1 JaxCoder.com Latest Article: EventAggregator
There are people/companies promoting 'Test Driven Development', writing all the tests, from module level and upwards, before any coding is started. I have even talked with people claiming to practice it :-) For all my private projects, I practice 'Documentation Driven Development': I write both (end) User Guide and system documentation (implementation language independent, as noted earlier) before I start coding. Admittedly, it happens that the 'ideal' view of the system, described in the documentation, cannot be realized 100% in practice. Yet I would say that having the 'ideal' solution in the documentation is a great help to make sure that adaptations are done in a structured and architecturally sound ways, so that they do not appear as random hacks. Both end user and system documentation is of course updated correspondingly. The one big software suite I was working on that tried to follow a TDD style (admittedly, tests were implemented in parallel with the code, but by a completely independent team) did experience very similar situations: The original spec, underlaying both tests and code, could not reasonably be implemented exactly as given, so both code and tests had to be modified midway. Specs are not carved in stone.
Religious freedom is the freedom to say that two plus two make five.
-
There are people/companies promoting 'Test Driven Development', writing all the tests, from module level and upwards, before any coding is started. I have even talked with people claiming to practice it :-) For all my private projects, I practice 'Documentation Driven Development': I write both (end) User Guide and system documentation (implementation language independent, as noted earlier) before I start coding. Admittedly, it happens that the 'ideal' view of the system, described in the documentation, cannot be realized 100% in practice. Yet I would say that having the 'ideal' solution in the documentation is a great help to make sure that adaptations are done in a structured and architecturally sound ways, so that they do not appear as random hacks. Both end user and system documentation is of course updated correspondingly. The one big software suite I was working on that tried to follow a TDD style (admittedly, tests were implemented in parallel with the code, but by a completely independent team) did experience very similar situations: The original spec, underlaying both tests and code, could not reasonably be implemented exactly as given, so both code and tests had to be modified midway. Specs are not carved in stone.
Religious freedom is the freedom to say that two plus two make five.
You sir are an anomaly. I know people that write a spec to go by but usually written by a project manager. But I guess if you are a one person shop that would be you. I start out with a general plan but, as an example my current project, I started with a very generic idea of what I wanted to accomplish and it just grew and grew. The one saving grace is that I programmed it so that it could expand...and it has grown exponentially. I document code pretty heavily as I go, but writing user manual or any kind of formal docs is VERY difficult for me.
Definition of a burocrate; Delegate, Take Credit, shift blame. PartsBin an Electronics Part Organizer - Release Version 1.3.1 JaxCoder.com Latest Article: EventAggregator
-
Hi, I have written a bit of Code to talk to bit of hardware. All good I now having to document it for the records, In the past I have worked on embedded and analogue test rigs which can be covered by a flowchart and a listing. This will not work for a Windows program there is too much going on compared to a PIC or Atmel. Is there a way of creating the asked for without going mad? It can't be too odd as I think there must be other companies who need this...
-
My experience with Doxygen (my own direct use and how I have seen numerous co-workers use it) is that it is fine for the bottom level documentation. The reader will know all the details about the third argument to a given method, but without a clue about when, where and why that method is called at all. The protocol, both any line protocol and the protocol of interaction between methods in one module and the interaction between modules. In principle, you can add information about module and object interaction, line protocol specifications etc. My experience is that developers never get around to it Round Tuit[^]. Documenting the third parameter in a Doxygen comment is easy to do when you are editing the code; the higher level documentation is postponed until the next tuit delivery. (But sending the order has been postponed ... :-)). As long as the intermediate levels are documented well, from the top level, the main subsystems and their interactions, and then stepwise down to modules and objects, then the reader might as well dive right into the source code. When you understand the use of some component, you have no need for a Doxygen carbon copy of the details that you will find in the source code anyway. Too often, Doxygen 'documentation' is little more than a rephrasing of method header. Obviously, this very much depends on how developers use Doxygen. I am referring to what I have observed, not what you in theory can do with Doxygen. Equally important: This is certainly not Doxygen-specific. Give the same developers another documentation system that they can maintain as part of the code editing, and the result will be very much of the same. You see it everywhere, in almost all software and documentation available on internet: Method headers and parameters are documented; how these are intended to be used is often completely omitted. If there are some traces of it, it is often poorly written. (The best way learn the use of some library, server etc. is to search for some other open source code to see how they are using it!) So, my advice is: Forget about the source code documentation, at the method header and parameter level (with the exception of APIs exported to users outside your organization). Document it top-down, with focus on component interactions. If there are explicit protocols across a line, describe it, but document the protocol, not
"So, my advice is: Forget about the source code documentation, at the method header and parameter level (with the exception of APIs exported to users outside your organization). Document it top-down, with focus on component interactions." This right here.
Charlie Gilley “They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759 Has never been more appropriate.
-
Welcome to a reason I don't do desktop and server development anymore. The truth is I've only ever done flow diagrams for embedded code. To verify desktop applications, rather than design a flow diagram, I design a test matrix. My functional requirements basically dictate the tests. If you really must diagram your software's behavior, you could use UML, but it won't make things easier, just more comprehensible because anyone with a UML background could understand it. UML - Behavioral Diagram vs Structural Diagram[^] Adding: To my mind this is the difference between programming realtime systems and programming non-realtime systems - realtime systems are predictable enough to diagram. As a rough rule of thumb anyway.
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx And my IoT UI/User Experience library here: https://honeythecodewitch.com/uix
uml - meh. never met anyone that used or understood that garbage except for the ump prophet.
Charlie Gilley “They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759 Has never been more appropriate.
-
Hi, I have written a bit of Code to talk to bit of hardware. All good I now having to document it for the records, In the past I have worked on embedded and analogue test rigs which can be covered by a flowchart and a listing. This will not work for a Windows program there is too much going on compared to a PIC or Atmel. Is there a way of creating the asked for without going mad? It can't be too odd as I think there must be other companies who need this...
And "It can't be too odd" you'd be wrong. I have seen so many developers blow past this area it makes my eyes water. Marc has a good list, but personally I would condense it. The real question is, what are your doc requirements? I had to write MILSPEC docs a long time ago. DD something or other, very specific and completely useless. I went to the USAF Captain handling the project and told him I could give him what he asked for but it would be complete crap and useless. Alternatively, I could give him something useful and we just wrap it in the boilerplate of the doc spec. He was happy. - if you are documenting code stuff, it must be automated. Else, the doc will become a project of it's own, no one will maintain that part and worse, it will become obsolete and not reflect the code. Frankly, this is mostly useless documentation. - what you need to build the project - good stuff. Software to install, build procedures, etc. - my biggest career beef - I rarely come across doc that explains why the code is the way the code is, the abrasions, broken limbs and late nights of things that have bit you, and on and on. - DO NOT INCLUDE WEB REFERENCES TO INFORMATION. Especially Microsoft. Print the info in PDF form and archive it with the doc. Microsoft routinely prunes useful info for the misguided reason that nobody could possibly care about this any more.
Charlie Gilley “They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759 Has never been more appropriate.
-
Doxygen homepage[^] It's something you have to do as you write but when done it's a flexible doc system.
Definition of a burocrate; Delegate, Take Credit, shift blame. PartsBin an Electronics Part Organizer - Release Version 1.3.1 JaxCoder.com Latest Article: EventAggregator
Mike - would you email me at cgilley2640@gmail.com? I want to ask you a retirement question(s) offline. Used to be that CP would allow a discrete but direct email...
Charlie Gilley “They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759 Has never been more appropriate.
-
Doxygen homepage[^] It's something you have to do as you write but when done it's a flexible doc system.
Definition of a burocrate; Delegate, Take Credit, shift blame. PartsBin an Electronics Part Organizer - Release Version 1.3.1 JaxCoder.com Latest Article: EventAggregator
Mike - would you email me at cgilley2640@gmail.com? I want to ask you a retirement question(s) offline. Used to be that CP would allow a discrete but direct email...
Charlie Gilley “They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759 Has never been more appropriate.
-
uml - meh. never met anyone that used or understood that garbage except for the ump prophet.
Charlie Gilley “They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759 Has never been more appropriate.
I'm not a fan of it myself, but I had to learn my away around it back when I was a software architect by trade.
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx And my IoT UI/User Experience library here: https://honeythecodewitch.com/uix
