Re: How to write a "proper" math document
- To: mathgroup at smc.vnet.net
- Subject: [mg119979] Re: How to write a "proper" math document
- From: "McHale, Paul" <Paul.McHale at excelitas.com>
- Date: Sun, 3 Jul 2011 04:11:01 -0400 (EDT)
- References: <201107020902.FAA10576@smc.vnet.net>
Daniel, I couldn't agree more. We are struggling with the best way to document. Pasting into Word works, but is a secondary effort, as you said. I think there are two levels of writing for engineering. The first level is documenting what one has done or will do. The intent is little deviation once written. Unfortunately there is no increase in innovation by this process. I think it is better being able to learn something from writing the documentation. This is very difficult to teach. I believe Mathematica not only supports this but is one of very packages that will even come close to preventing the duplication of effort you mention when creating documents. The engineer must be able to experiment with models and math before implementation. I think two advancements are required. We, as engineers, need to accept the correlation between experimental writing and innovation. Too many treat the actual development as the "playground" or sandbox to experiment. I think this is prohibitively expensive. Changing documentation is cheap compared to circuit cards or distributing software. Experimenting in documentation is much faster. Care must be taken as models are always incomplete. Of course, so are first design efforts :). I'm also of the school that proper engineering starts with documentation. The actual implementation should be reduced to recipe. First design reviews should be of documentation where changes are "free". Unfortunately, the artistic/emotional side of engineers find this physically painful. It would be very helpful if IEEE or some other body would start a set of standards for documenting engineering work. CMMI was interesting but enforces no definition of a specific process. I think engineers are untrained/unskilled in this area and could use some standards. The second part is Mathematica needs to flow back and forth better between document (read mode for others) and development (all code visible...). This is especially true for people who don't know Mathematica. They will get lost seeing all the unfamiliar code. I find going from working with code to putting a document in presentation or readable form (hiding the code) is a lot of effort. Closing and opening code segments is too much of an effort. It would be nice to have two sets of properties, one for working mode and the other for reading mode. Just me 2c. Paul Paul McHale | Electrical Engineer, Energetics Systems | Excelitas Technologies Corp. Phone: +1 937.865.3004 | Fax: +1 937.865.5170 | Mobile: +1 937.371.2828 1100 Vanguard Blvd, Miamisburg, Ohio 45342-0312 USA Paul.McHale at Excelitas.com www.excelitas.com Please consider the environment before printing this e-mail. This email message and any attachments are confidential and proprietary to Excelitas Technologies Corp. If you are not the intended recipient of this message, please inform the sender by replying to this email or sending a message to the sender and destroy the message and any attachments. Thank you -----Original Message----- From: dr DanW [mailto:dmaxwarren at gmail.com] Sent: Saturday, July 02, 2011 5:03 AM To: mathgroup at smc.vnet.net Subject: [mg119979] Re: How to write a "proper" math document Mathematica is probably the best environment for what Donald Knuth would term Literate Mathematics or Engineering. It allows comments in rich text and typeset mathematics in the same document as functional code, data, live plots, and now interactive demos. The only other product that comes close uses another M product with LaTeX, but Mathematica has the edge over that one with the interactive demos. This is important to me as the director of a research department. I am trying to find ways to get my engineers to document their work. As long as writing documentation is a separate operation from doing work (calculations, data crunching) it will always take the back seat. However, if documenting is concurrent with working I don't have to tell anybody to go back and finish the job. Daniel
- References:
- Re: How to write a "proper" math document
- From: dr DanW <dmaxwarren@gmail.com>
- Re: How to write a "proper" math document