LaTeX for documentations in large projects

Hi Joe,

My condolences! It would be similar to manually verifying the code generated by a compiler -- you just want to TRUST it and hope it always behaves -- even if you put a cross reference in a footnote to a table located that's located in an appendix of a different document... etc.

I think the only practical way to develop consistent documents is to have "regular writers" that just crank out the prose, illustrations, etc. Then, "specialists" that massage this "raw input" into the structured form that the DTP tools require. Hence my earlier comment about a "Document Czar" -- who ends up being a *grunt*!

But, they should at least be able to understand the issues involved (moreso than, say, a "secretary"). Newer tools are DTD driven and can at least verify that the structure of the document that you are creating adheres to the rules for documents of that type. E.g., subheadings can't exist at the top level; headings can't exist below subheadings; etc. And, present that in a GUI-ish environment.

I think the larger problem is designing a document structure and anticipating the types of tags that will be needed at each level throughout. But, this responsibility can fall to the "Specialists".

I understand your point. However, I think changes made to the visual presentation of individual glyphs (i.e., italics, different type family, etc.) are intended to be significant for SOME reason. Just calling them "italics" or "bold" sidesteps that reason. And, invites others to concentrate on mimicking the *appearance* of some other semantic tag WITHOUT actually bringing the semantics along with it!

E.g., in the documentation for my gestural interface, I tag the names of all gestures with . So, references to "circle" that aren't tagged thus ("The buttons are arranged in a circle.") don't appear as gestural references ("Issue a Circle to invoke the help menu"). Manually proofing said documents (in final rendered form) would be too tedious if a writer could arbitrarily alter the appearance of "Circle" to resemble its appearance as a -- without explicitly tagging it as such.

(It also simplifies things like index preparation, special cross references, etc. as the MEANING of individual bits of text is indicated by the tag. Imagine naively indexing every reference to "circle" -- even those that were not indicative of gestures!)

I've seen this tried, and it did not work. The regular writers had no idea what they were talking about, and babbled. The result was beyond repair in the sense that the cheapest approach was to discard the babble and start over with people who did understand.

A war story: Many years ago, I had a Chinese programmer working for me, and we needed to document his (very good) code. He normally escaped doing documentation because his English wasn't nearly good enough. My solution was to tell him to write the first draft of the documentation in Chinese and translate it into rough English, and then work with one of our Tech Writers (a native speaker of English). This yielded a pretty good document, because while the Tech Writer did not initially understand the software being documented, the programmer did, and so could organize the presentation. The Tech Writer cleaned up the English, and acted as the readers' proxy - if the Tech Writer didn't understand something, he asked the programmer. Repeat until done.

They are always very technical, but in the domain of the standard. Usually they are also comfortable with the editing tools, such as Frame.

I've seen tagging done for the POSIX standards, but then these standards were written in a purpose-built version of runoff.

This kind of thing was done in the scripts attending that specialized form of runoff used for POSIX, but then the Tech Editor was a world-class programmer.

I very much doubt that Power Society standards have any such thing.

Joe Gwinn

Ah, I don't believe in having folks who don't understand the product (or whatever it is that is being documented) preparing documentation!

Rather, what I was addressing was to separate the PUBLICATION needs of the document from the TECHNICAL issues being described. Presumably, you have someone competent in the technology that can read the prose written by the "writers" (e.g., these writers may be "junior programmers" when it comes to documenting software; "technicians" when it comes to documenting hardware; etc. -- they need not be the original authors/designers of the works being documented... BUT, are technically proficient in the vocabulary and concepts that would be used by those "original creators") and massage it into a form (and consistent presentation/appearance!) that gets you the last

I.e., split the effort into different sets of skills to get from A to B (via C).

Most programmers/engineers are lousy writers -- they tend to forget who they are talking to as well as the types of issues that may be important to that audience.

Similarly, most *writers* (e.g., Lit/English majors) have no concept of the technology that is being presented.

I think you have to go from hand to hand (to hand) to get to a finished document product. This is hard to do in small shops who probably don't treat documentation as anything more than a checkoff item. (some of the manuals I've read are abysmal! even from large multibillion dollar corporations -- as if they assumed no one would ever READ them so why bother putting any effort into WRITING them?!)

So, they just need to be conditioned to adopt a consistent tagging methodology. Probably difficult (getting agreement) in such a large "organization". OTOH, probably easier to *enforce*! :>

I think it has a lot of value as the documents become more tightly integrated with the products. Currently, most massaging of documents happens in the design (and documentation) phases. Once created, they tend to be largely static and "ancillary" items. E.g., the product never actively references them or incorporates them into its nominal operation.

All these "advances" are obviously geared towards making documents more useful and more of a "product resource".

I don't think that should be necessary for this sort of thing to work. However, it may require the A->C->B sort of approach I mentioned earlier.

Wow. In my workplace we use MSWord for documents in the hundred page region (and below) to well over 1000 pages. We do not use many of the fancies when we do it, which may be key to success. Indeed a lot of the embedded fancies would fatally corrupt our documents in a retroactive heartbeat.

?-)

When was this? No doubt things have improved since that war story.

And our workarounds were simplifications, so Word wouldn't lose the bead.

But Word was never intended to meet the needs of a publishing house and its workflow.

Joe Gwinn

Well, yes, and that's the point of my little war story. The fact that the programmer was Chinese only strengthens the example.

It's because we in the US no longer teach writing in High School and before. Writing is work, and there is an artifice to be learned. We don't teach grammar either.

By the way, we are not talking about being able to write the Great American Novel. We are talking about writing a simple descriptive paper. I heard from a colleague that a standard test used to qualify candidates for a Technical Writing job - ask the candidate to write an instruction sheet on how to tie one's shoes.

Teaching writing is expensive, because the student-teacher ratio cannot exceed ten, or the teacher won't have time to do the detailed correction that's needed. One of the big distinctions between US public (tax supported) and private (parents pay) schools is that private schools all teach how to write.

Hence they babble, or balk.

There is the key. It isn't valued. And, as you mention most programmers are terrible writers, so they will use any excuse to avoid writing. The problem with my approach of attaching a Tech Writer to the programmer is that it's expensive, and you have to have some Tech Writers on staff to assign.

The problem isn't that they are stupid. The problem is that they usually don't see the reason to go to the trouble., and it's painful to learn without the background.

In the case of teaching stack order to typists, they were willing because making tables and nested tables was driving them nuts, so they had motive.

Parallel War Story: The lab director's secretary complained to me that the mouse didn't work, and the cursor would fly off in odd directions. I couldn't find anything wrong with the mouse, so I watched her work. Turns out that she was pointing the mouse in the direction she wanted to go, and then moved there. She had no idea that one held the mouse axis vertical regardless, and telling her didn't quite work. So, I took the mouse apart as for cleaning, and showed here the little wheels, and demonstrated that if I rotated one wheel, the cursor went up and down, while the other wheel caused side-to-side motion. Also cleaned the mouse. Problem solved - she now had an adequate mental model of how the mouse worked.

Yes. But it is always an investment decision.

My general point is that tags and scripts are a programming effort.

My other point is that tags and scripts is a lot of work, and so is subject to cost-benefit analysis.

Joe Gwinn

Not sure that follows anymore.

No, engineers never made good writers. Technical writing has always been a specialty. The difference is that now there are few companies that want to invest in them so it's too often left to those who aren't qualified.

Good plan but don't expect the average engineer to do it. It's not their specialty (among a whole host of other reasons).

Those are some absolute statements that will require support to be believed.

Why should they even be asked to venture outside their training?

Exactly, and that has nothing to do with the current state of the schools. People are expensive. Talented people, even more so.

When we switched to Frame, they sent everyone to a week-long class, not only to learn Frame but to unlearn everything we'd done before (e.g. one does *not* use to create white space). "Use the template" was the directive. I thought it was a very good use of the week and after I really liked using Frame.

Most just pick it up in a minute, just by moving the mouse.

People are still people.

Some were good writers, some were not. I've met both kinds.

The classic books in any field are almost always written by people who are good writers.

I have observed that technical books written in the UK are on average better written than those written in the US. I gather that this is because they still teach all students in the UK how to write, whether they want to or not.

And it cripples them. I see it every day.

This is from personal observation and talking to people who went to private school. If you need mathematical proof, go right ahead.

That was my original point, saying that having the non-engineer writers go first won't work. And I've seen it tried.

Actually, on a radar system many years ago, I saw the tech manual writers struggle to generate anything useful, and so decided it would take less of my time if I just sat down and wrote the rough first draft. One cannot just deliver muck because the customer verifies the usefulness of these documents by trying to follow them.

No, it's exactly on point. The problem being solved by addition of Tech Writers is exactly that engineers are able to graduate without being taught how to write a comprehensible paper.

I learned Frame from a book, and there was a learning curve for sure.

A lab director's secretary is never a kid. She was from the old school, and had little prior experience with computers.

If you want the fuller explanation, read some of the human interface guidelines documents from Apple in the 1980s, especially the book by Tog (I don't recall his full name, but it will come to me - Tog is a clip of his last name).

Joe Gwinn

I would think using "fresh hires", "junior staff", etc. would be an EXCELLENT way of filling in the "middle position" in the above chain. It allows that individual to become (intimately!) familiar with your products without having the responsibility of making design or implementation decisions. And, encourages building writing and communication skills in the process. Likewise, has prepared him/her for the eventual "very proficient" role in which he/she will have to be aware that others will be trying to DECIPHER and EXPLAIN his/her design/implementation decisions!

I.e., the value of consistency in the design as evidenced by teh relative ease with which a consistent design methodology can more readily be documented/explained (hopefully, a lesson he/she learned while filling that middle role!)

Dunno. School, for me, was many decades ago. But, I recall a fair bit of emphasis on "English" throughout elementary and junior/senior high schools. E.g., you couldn't be awarded a high school diploma without having had 4 years of English -- the same was not true of Math, Science, etc.!

Correct. But, IMO, it's more than just being able to describe something. You have to be able to see The Big Picture and come up with a strategy for describing The Whole Enchilada. You don't want to write several discrete, distinct chapters that don't "fit" well together.

E.g., the first writing contract I took on was to document an existing device (for which the exiting documentation was universally recognized as abysmal, incorrect, out-of-date, etc.).

Not knowing anything about the device, I had to first familiarize myself with it, how it would be used, the types of things you would want to do with it, the types of details you would likely *forget* (without continued exposure), etc. I.e., if *I* owned one of these, what would

My prose ended up very stilted -- more like the "classic" technical writing style (dry, as if enumerating facts). But, to my credit, I was told old customers were cold calling *requesting* to BUY copies of the "new manual"! The gentleman who provided support for the device commented, "There hasn't been anything that I have been UNable to find in the manual!" I guess a testament to the structure I laid out for the document, the actual "presentation", depth of index, etc.

You knew *where* to look for whatever it is you sought!

Since then, I've been concentrating on how to "soften" my prose and make it more "conversational" -- lead the reader to a specific understanding instead of bombarding him with a set of "facts".

Sensible. I always used "change a tire" as a programming "test" (did you remember to pull off to the side of the road? OPEN the door before getting out? How are you watching for oncoming traffic WHILE you are focused on removing the flat? etc.)

No idea. I went to public schools and *think* I can build a sentence properly (though I have a persistent problem with spelling... especially doubling consonants! :< )

I think a bigger problem is people's inability to organize their thoughts, well. Hand someone a piece of paper and tell them to write a piece of code, a story, etc. and they will stare at it, unable to begin.

Give them an EXISTING piece of code, story/outline, etc. and they'll usually have no problem "fleshing it out"!

I was thinking that the "junior programmer" (middle person in the aforementioned chain) could "translate" the technical issues into something resembling "English"; then, someone skilled in writing and document prep could translate *that* into REAL English -- without really having to "understand" it!

It may be that "written materials" are not valued! E.g., the tiny user manual for our washing machine (big company!) is full of errors and "bad translations". Is this because they have crappy staff? Or, because they figure they don't NEED to invest in these tasks as

(How many folks have read the LENGTHY "user manual" that accompanies most new automobiles? Or, the instructions for their cell phone? Or, the manual for their VCR/DVR/washing machine/computer/programs/etc? Why invest the time in preparing a document if its never going to be read?)

I am relying on the same approach with my docs! Have the documents play a key role in the design of the product so that the path of least resistance is to keep the documents up to date. Make it more tedious for the next developer to work *around* the documents than it would be to work THROUGH them!

That's the point -- make it an investment that has a real payoff! E.g., automates some of the code generation; or, addresses some portion of the "user documentation" that will eventually need to be prepared, etc. So there is an incentive to preparing and maintaining the documents!

Writing == communication. If you can't "build" an explanation (or "argument") on paper, you probably can't build it with the spoken word, either! How do you organize your THOUGHTS if you can't organize your *words*?

Listen to how those around you explain things that are of personal interest to them (or, work-related experiences) to others. Do they cling to their own, application-specific terminology? Magically expecting everyone around them to understand their technical shorthand? Or, do they make an effort to relate their subject in terms that their audience is *likely* to understand?

I had a lady coworker once jokingly berate me for explaining computer-related issues using *kitchen* analogies -- as if I was being misogynistic! So, the next "problem" she presented to me I opted to matter-of-factly explain in "bedroom" analogies. When she had achieved a suitably uniform shade of RED, I paused and waited for her to suggest I return to the kitchen domain, again! :>

But, in each case, she ended up understanding the issue that others had tried explaining/resolving with techno-babble.

Actually, I usually write an analytical and/or tutorial memo while solving a problem because I find it helps me to clarify my thinking. And I get a nice memo out of it.

Would have been fun to watch. You must have known her well, to get away with that.

Don't think I'll try that approach. It would probably end badly - the lawyers would be babbling something about creating a hostile environment as the guards frog-marched me out the door.

Joe Gwinn

The college hires don't yet know enough for that to work, and will babble as badly as the English majors, only slightly more plausibly.

The requirement is still something like four years of English. What varies is the content of "English".

Well, yes. But if that cannot do the simple description, they will not be doing the grand sweep either.

I'm glad to hear this, but my immediate reaction was that you were fortunate to have a boss who was willing to pay for your education.

Yep.

This isn't a writing test, but another colleague of mine tested the knowledge of UNIX system admins and programmers by giving them a piece of paper and asking them to describe and diagram the boot sequence of UNIX. This is a very effective filter.

This is a different problem. Teaching someone how to write does not ensure that they have anything to say.

As discussed above, it takes a while before the college hires figure things out.

There is an air of circularity here. If the manual is worthless, why read it? If people don't read manuals, why write good ones?

Some companies are famous for good documentation, and some are famous for the converse. I've never heard of a company that dies because their documentation was bad.

Joe Gwinn

I am dismayed at how much ends up "lost to posterity" due to inadequate or incorrect documentation. I've been trudging through many "classic" research papers *chagrined* at the typographical errors that make them less than (immediately) useful! In some cases, contacting the original authors has proven difficult/impossible. And, in other cases, the original author may no longer recollect some of the fine detail that I am questioning -- and, have little interest in "investigating" their old works.

So, I'm left with the knowledge that something is (should be?) "do-able" (allegedly) -- yet not having a clear path to repeat their prior successes (or, even TEST against them!)

As I want the things I am working on to be "self-supporting" (i.e., *I* don't want to spend my time answering questions), I have been attempting to document them in a more "educational" manner.

It is impractical to document hardware or software in anything more than a "theory of operation" manner. There's just no provision to explain and explore alternatives *before* arriving at the eventual implementation as a "conclusion".

So, I try to build free-standing documents that educate on a particular aspect of a problem. Then, ASSUME the developer has read these so I can just refer to their results/conclusions in the hardware/software documentation -- without having to explain them (again!), there!

Yes, you could say that! ;-)

The point is/was, to find a way of explaining an issue in terms to which the other party will be able to relate! Listen to how often people try to explain things AS IF they were still "at work" talking to their peers/superiors.

"And, you expect me to PARTICIPATE in this discussion? How??"

Technical people are particularly bad in this regard. They forget that language and terminology that are commonplace in their "element" are jibberish (or, worse -- MISUNDERSTOOD!) to others not a part of that community!

Yeah, nowadays, the workplace is far less tolerant of this sort of stuff! Sad as this sort of familiar/casual interaction can be great at tearing down boundaries between people/groups. I.e., "being able to take a joke"...

Perhaps I have the benefit of having been surrounded by "more adept" peers? If I restricted my selection to those with English as their native language, *any* of the folks I went to school (college) with could easily do this -- AND, appreciate the logic behind it.

It might take some time for them to develop a good "approach" to each assignment (i.e., avoid the temptation to start at "main()" and describe the code sequentially). But, I think they would be smart enough to know not to (for example) just repackage the comments that accompany the code!

Again, I guess I can't imagine what it could be *other* than "reading and writing". At the end of my High School stint, they were starting to introduce courses like "Film Appreciation", etc. -- but, those were distinctly *not* "English".

I recall there was an emphasis on American Literature -- one year in High School and another in Jr High. Ditto American History. I was actually surprised, in college, to encounter other "Americans" who had not had these exposures! I.e., I deliberately chose courses of similar titles for college "electives" knowing that I had already seen much of that material, before! :-/

The client gave me the opportunity to learn (by awarding me a project that required this skillset). The learning came out of my pocket as the job was essentially fixed cost (they got a GREAT deal as I prepared dozens of illustrations, schematics, code samples, etc. and documented

There was exactly *one* pass through the process. My first draft was the *final* draft. (I am very thorough :> )

I see knowing how to *approach* a problem (whether it is writing a piece of code, designing a circuit or documenting a device/interface) as a necessary skill to effectively complete the task "unassisted". If you can't sort out how you are going to "pitch" some information to a faceless reader, then, chances are, the reader will end up confused and find little value in what you end up writing.

Exactly! The real question, then, is: if you prepare good documentation, will it be VALUED? Will it be consulted? Will it even be *kept*??

Yup. The most common metric, currently, seems to be "price". As such, why do *anything* (documentation, improved product quality, etc.) that will adversely impact price??

Two things that make your point silly:

2) US citizens of Chinese ancestry often do better in school, English included, than those of European ancestry.

It's a different skill set, one that uses completely different parts of the brain. One cannot expect even the best engineer to have the capability to do technical writing.

Many are horrible writers. Many Textbook authors come to mind. Those with both skills are a *SMALL* subset of the universe of engineers.

Or perhaps that says something about the textbooks you've been exposed to.

If their job is technical writing, sure. It shouldn't be.

"cannot exceed ten" and "private schools all teach" means that you're stating that you have data that shows the absolute is true. That's just silly. Perhaps you're not as good at writing as you think you are?

There *is* such a profession called "technical writer". They're trained as such. My SIL was one, many moons ago.

That doesn't support anything you've said. Of course it's a good idea to have input from the designers. In fact, the first documents should come from marketing (what are we trying to build) and the system architects (how are we going to approach the solution). The designers may fill in some detail (or not).

Bullshit. There are fewer technical writers now than there were in the past. It's not some revelation that engineers, in general, are poor writers. This was true fifty years ago and if what my father complained about, it was true a generation before that. The two take a very different set of skills and aptitudes.

Doesn't matter. It's a simple device. Two minutes play should be all that's needed. Learning context and buttons complicate things a lot but any bloody idiot should be able to pick up the motion, for themselves, in a couple of minutes.

You're saying that Apple wrote a book about the 2D motion of a mouse? Perhaps that says something about Apple's customers. If they needed that book, I'm surprised they were able to read it.

Well, my story was one approach to getting good documentation from a programmer who could not write understandable English documentation. Have you a better method?

Where was that claimed?

But there are engineers that are also good writers, as discussed next.

Well, I have a sample spanning many decades, and easily read ten books a year.

The problem is that they cannot convince other engineers and managers of the correctness of their approach. Or write a reasonable proposal section. This happens long before issues of documentation come up.

Non sequitur. I said it was my personal experience. My ability to write was not at issue.

Again, in this example, I came to the conclusion that it was best if I wrote the first draft, and did so. Your experience may differ.

Well, I don't know if the total number of Tech Writers has changed or not. I haven't noticed any such thing in my corner of the swamp. Perhaps you would like to support that statement by finding the relevant statistics on the US Bureau of Labor Statistics website.

Umm. Nice theory. Didn't work out that way.

And telling the lab director's secretary that she's an idiot may prove career-limiting.

Right. There is far more to it than that. Enough to fill a book:

"TOG on Interface", Bruce "TOG" Tognazzini, Apple Computer Inc, Addison-Wesley 1992, 331 pages.

Joe Gwinn

These systems are very large and complex, and it takes a year to really learn them.

There has been a lot of dumbing down over the years, often in service of political correctness and fads in teaching methods.

Yes, but the problem is the factless writer.

It's because for all their complaining, customers still buy.

Joe Gwinn

Usually, it's a real theory of operation that I most need. Without this, the myriad details mean little.

Yeah. My wife retired from the Finance business. It took some years, but I did learn more of her jargon than she learned of my jargon.

I did have a lot of fun teasing the true believers by mentioning that my wife very much regretted the rise of political correctness, because it killed all the good jokes off.

Joe Gwinn

For software, there are often far too many *different* approaches to a problem. Explaining why you chose a particular approach -- and its merits over the unnamed others -- can do far more for bringing the next developer "along" than any sort of detailed discussion of the *current* implementation.

E.g., where break-even points happen to exist between algorithms. Or, pitfalls that one might have from which another is immune.

It also lets you demonstrate many of the boundary conditions that someone might not otherwise be aware of. So, instead of "don't touch this piece of code", you can reference the particular special case that it protects against.

E.g., if you have a Bezier curve in which all control points are colinear, it's a piece of cake to compute it's "length" with simple arithmetic. OTOH, other schemes (e.g., De Casteljau's) can fall apart silently!

I don't think folks do this intentionally. Rather, they just get so accustomed to their "niche-speak" that they forget that there is

This is where "familiarity" often wins out. People know your *intent* and can look past the words: "Oh, that's just Don being Don..." Being OUTRAGEOUS often helps as any more subtle comments can leave people wondering if you meant what was SUGGESTED by them.

Sunday lunch! Finestkind! :>