Subj : Doc/noDoc? (was: CV, work-history, 91C, CompSci?, Applet? ...) To : comp.programming,comp.software-eng From : rem642b Date : Wed Sep 14 2005 09:52 am > From: Chris Hills > There is a system called Literate Programming where the > documentation and the source are the same thing. ... > It never caught on. Started out using Pascal and TeX At a minimum, the documentation for an API function should tell what the parameters really are supposed to be (as opposed to mere mnemonic names that just give a clue what they are), what general action is performed (both results computed, and side-effects on parameters and/or globals), and what the return value really is exactly. How can that useful information be represented by the source code itself? Or do you mean that it isn't the code itself, but rather comments interspersed within the source file, but not part of the source itself, are the documentation? Given that TeX is rather inscrutable, since it's based not on the nested structure of math expressions and the semantic meaning of the atoms, but rather on the manual shifts to superscript and subscript that would be present in a linearized sequence of typewriter actions and the particular font used to represent each atom, how can TeX by itself (without compiling it to printable format) be acceptable documentation? Now if comments in the source file contained directives which were compiled to produce separate documentation, as is the case with JavaDoc, that would be something entirely different. > Yes I agree HTML or more often XML I think is becoming the norm as it > can do more in on-line documentation. However this includes fancy > colours, fonts, links and diagrams not plain ASCII XML doesn't have any fonts etc. All of those user-presentation issues would be handled by a stylesheet which is separate from the XML document. So are you saying that nobody looking for documentation would read the XML data directly as an indented text file, but rather the XML data would be compiled via a stylesheet into a XHTML document which would then be rendered in a browser/viewer of some type? If so, I rather like the idea of the programmer using XML to write the technical part of the documentation, while somebody who knows next to nothing about programming but who is good regarding visual presentation issues maintains the stylesheet. > My worry is that he is not gainfully employed doing "something". That bothers me too. I wish that somebody would hire me from time to time, so the idea of being "between jobs" is more credible during times of unemployment. (Of course being employed all the time, as I was until 1991, with the next short-term project already waiting for me as I finish the previous short-term project, would be even nicer.) > I have done many jobs as times and conditions dictate. Apparently you have been fortunate that if nobody offers you a job in some area where you have experience, somebody else will offer you a job in some area where you have no experience whatsoever. I haven't been so fortunate. > However not to work for a decade because no one offers you one type > of job. You misunderstand the situation: Nobody has offered me *any* job of *any* type whatsoever recently. I even applied as a cashier at a gasoline service station, and as a library page, but wasn't given either job. (The library page job had about a hundred applicants for two positions, in 1999, before the current recession started). > I note that when I suggested a change of career the response was "I > have" from bespoke Sw to commercial SW. To my that is not a career > change. That is just a slightly different type of project. From funded research and R&D, under supervision of a university (funding from NSF, IBM, and sometimes university special funding), to commercial software-for-sale: Virtually all the job ads require 3-5 years shipping commercial shrink-wrap products. None of my 21 years prior R/R&D research ever shipped a commercial software product, especially not shrink-wrapped, so given that none of my prior experience counts for anything in seeing a new job, I see it as a career change, where I must start out at entry-level in the new field, where the old field would be of much value to me personally in understanding some aspects of the new career, but the new employer considers me to have no relevant experience whatsoever. > The answer is to get out there and do something. If you mean go to some company, walk in the door, and start working, without permission of anyone at that company, that's a crime: Trespassing. .