ideas on document set preparation process

on

the

documentation,

in

must

each

browsable.

$3Alatex/sci.electronics.design/fOOSbr_gkbQ)

Bleeding twit. Latex by itself is nowhere near what is needed. At a minimum and full up RCS is needed, like cervesa, or maybe even a content management system (CMS).

?-)

Then you need a document system that allows you to embed *references* instead of *copies* of data. In its simplest form, this would allow you to update *the* original instance knowing that it would propagate through the remainder of the documents (i.e., all references *to* it).

[Note that this requires some discipline on the part of the document preparer -- ensuring all "references" are truly *references*; structuring the "referenced section" in a manner that is relatively consistent (so that portions of it can be referenced systematically); etc.]

Ideally, the documentation package would support a "where used" capability so you can *see* these relationships present in your documentation tree (and, understand potential consequences of changes: "Ooops! That may also affect the environmental conditions in which the device operates!")

Think of it (on a trivial level) as using manifest constants in lieu of hardcoded values in source code. Change the constant and everything that derives *from* it automagically changes. grep(1) your files *for* the constant and you know "where used".

where_used("interface_to_external_subassembly_X")

Which one of your PROGRAMMERS is designing the circuitry? Laying out the board? Designing the mechanical enclosure? Fixing the leak in the Front Office's bathroom? Preparing the Annual Report for stockholders...?

Exactly. Especially if "documentation" is an important part of your product!

I think your efforts are just going to give Management an excuse to NOT address the problem. And that's fine -- if you folks want to spend your days writing documents instead of writing code, etc. Hey, if you get good at it, maybe Management can also have you tackle those Annual Reports... and, the leaking toilet!!

I.e., you are giving them that "solution" that you indicated they'd need before presenting a "problem" -- and the solution comes entirely at YOUR expense.

Ah! *I* do! "Call me when you know what you want". How can you commit to a cost and delivery schedule if you don't know what you're making?

"Hi, Al. We'd like you to build us a small office building. How long will it take and what will it cost...?"

"Al, we want to know when we can count on that *boat* we've asked you to construct to be sea-worthy. Oh, did I forget to tell you that we (now) want a *boat* and not an office building??"

I just can't see how you get quality in a process like that. Unless you THROW AWAY everything that you have done up until that point -- because there *will* be assumptions in what you have done and you WON'T be aware of all of those. Instead, you will be under (self-imposed?) pressure to think you can reuse many of the items you've built/started up to this point -- without going back and verifying that ALL of your initial assumptions are still valid.

I.e., *if* you had LOST all of this work, would you recreate it in the same manner, now, knowing what you do know, now? If not a RESOUNDING "Hell, yes!", then why not??

Sure. You treat every information exchange as a mini-project with its own "sign off", etc. You don't pass scraps of paper back and forth "in passing" as you encounter each other in the cafeteria, etc. If you have FORMALLY provided this information to the docwriter, then that becomes a contract that can be verified and enforced. *He* is your customer (as proxy) in much the same way that you have obligations to the "full project".

Exactly. The writer speaks the language of the developers and conveys that to *his* readers (which may be "simple users", auditors, test staff, stock holders, etc.). You hire him (them) to know all these "conversation domains" and be capable of organizing and presenting information in a manner that maximizes its utility and accessibility.

Can simple prose convey the meaning, here? Is an analogy in order? Perhaps an illustration or photograph? Are the salient issues

*obvious* in that illustration or are callouts needed to draw attention to them? How best to present this information in tabular form? etc.

Not sure how well "demands" from BELOW are met, in your corporate culture. IME, what gets results is losing business because you can't satisfy the customer's needs. If your staff are *somewhat* meeting them -- but at your own expense (uncompenated time; longer hours; dissatisfaction with the job; etc.) -- then Management often doesn't *see* a problem (just a bunch of grumbling engineers)

IME, employers/managers/supervisors/project-leads are slow to dismiss staff. Especially if those folks are already engaged on a project and facing deadlines -- "A problem (person) you know is better than a problem unknown!"

But what incentives do any of these folks have to "stick their foot out" and interfere with "progress" (i.e., defined as "getting ALL the requisite signatures so you can check this off your list")? Anyone who "objects" to the content draws attention to their *objection* -- impediment.

Said another way, what *compensates* for the potential scorn, derision, pressure, etc. that they are likely to encounter by slowing the process? ("Sheesh! It's GOOD ENOUGH! Why is he/she objecting? It's never been a problem BEFORE...")

I.e., you tend to get this sort of "dedication" (willingness to put up with the "crap") from people who have placed high PERSONAL value on quality instead of "just get it out the door".

They won't "go elsewhere". Instead, they will do what is *minimally* required to CLAIM they are compliant with the standard. They comply with the *letter* of the requirement, not the *spirit*. And, because they have done so, you have no "valid" recourse to discipline them on their actions.

"I thought 'r' was a great name for 'revolutions_this_time_interval'. What's *wrong* with that choice?"

Again, what incentive (besides personal BELIEF) does he/she have to take on this effort? It's not his/her name on the corporate letterhead! He/she will *still* get paid, this week. If the company fails next month/year/decade, chances are he/she will have "moved on", already.

You want good practices AND people that BELIEVE in them. So, they WANT to "do it right".

I've seen places where an individual can disrupt the group dynamic disproportionately. This can be "one bad apple" amongst a group of great performers... *or*, one great performer amongst a group of POOR performers.

As an "outsider" (consultant), I often catch a lot of heat when *hired* to fix something (or *do* something that the organization apparently can't). There's rarely "universal gratitude" from everyone involved. Staff can feel resentment that I've made them "look bad" ("Sure! It's easier for

*him* to do this... look at what he's getting paid! He doesn't have to deal with the politics, here. Or, the lack of proper equipment. Or, all the silly meetings. Or..."). Similarly, (middle) management can be resentful ("Why can't you get this sort of work out of YOUR staff, Bob?")

In a RATIONAL world, everyone would be thrilled that a problem that had previously NOT been solvable has *been* solved. And, *learn* from the experience.

I think you stand a far better chance of getting to your goal if you can bring all invested parties to the same concensus as to the *needs* that are not being addressed, properly. How you do that in *your* environment is something I can't answer without experiencing it for myself.

Over the years, I've developed a "short list" of folks whose opinions and work ethic I value. There is rarely concensus among (all of) us as to the right solution in a particular problem. But, I know that all would

*embrace* any such solution based solely on its origination from one of these peers ("Well, we can *try it* and see how well it works. And, revise our approach based on what we learn in the process")

Off to make another batch of pizzelles... another week and this'll all be behind me! Yay!

The more i read and think about this, the closer it comes to a dependency management system. A lot like the ones used to manage linux unit packaging.

??-)