Hi everyone, after some search on the web and some inspiring discussion held here on using LaTeX for projects documentation (see news: snipped-for-privacy@mid.individual.net), I realized that in the Military and Aerospace sector it exists a standard for authoring and publishing technical documentation: S1000D.
Unfortunately one thing is knowing it exists, another would be to understand how much would it cost for a 70 people company to switch from a totally unstructured and painful authoring process with MS Word, to a compliant process supporting the standard. And whether it is really worth id [1].
There are certainly some non-recurring costs (like process implementation, databases infrastructure, training) and some recurring ones (like tools licenses), but *if* the authoring, included reviewing, process increases its efficiency, it would be easy to calculate the ROI.
Anyone here with some experience on transitioning from 'MS Word chaos' to S1000D?
Al
[1] I'm under pressure to deliver a datapack of docs and 98% of mods and comments from our PA are about inconsistencies among documents...WTF!
--
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
A: Top-posting.
Q: What is the most annoying thing on usenet and in e-mail?
Before you take any steps (in *any* direction!), you have to accurately gauge how important documentation is (REALLY IS!) to your organization (ultimately, customers). Not just "lip service" (e.g., EVERYONE says "quality" and "service" are important -- yet their actions and expenditures belie what they
*really* feel on those subjects!).
Look at where the folks responsible for this stuff lie in the corporate hierarchy. E.g., if they report to Manufacturing, then their needs/requirements/dictates will always be SECONDARY to Manufacturing's ("We've got to ship product! Screw the docs!")
I worked with a firm many years ago that put "Safety" in that sort of position, hierarchically. And, wondered why they had "safety issues" (from time to time). When "Safety" was later restructured to report to the CEO, the emphasis changed -- you
*had* to address Safety's concerns in design, development, manufacturing, documentation, etc.
If it's "just you" being charged with this, then, chances are, your organization is treating this as a check-off item... not a sea change in the way they do business!
hi Don, apologies for my late reply, it's been a crazy week at work.
[...]
we build electronics systems for space applications and documentation is really everything, from analysis to reports, to manuals. Through a project's life we have roughly a dozen formal reviews with our customers and we submit roughly 40 individual documents at each of them (including new issues of the same doc).
References amongst documents are vital since it allows to track what has been done for each design configuration. A thermal analysis it better be done wrt the part list and schematic annexed to it!
Not just "lip
we have no choice, our documents are reviewed dozens of times, internally and externally, in order to avoid any inconsistency. Yet, whenever the inconsistency survived the peer review chances are that two subsystems will behave erroneously because of that and debug time never ends.
Ensuring the inconsistencies are avoided 'by design' allow everyone to focus on the content and review process will be easier to carry out.
in our regulated environment the product cannot be delivered without the docs, no chance. Our PAs guarantee the doc is done and our technical managers guarantee it's done correctly. My only issue today it's that it takes too much of our efforts.
For safety related equipment, reviews and analysis are far more complex (and expensive), putting safety behind something else is not allowed by inspectors in a regulated (and healthy) market, unless you are talking about a politically supported operation where success was far more important than safety.
the whole engineering department is affected. Every single project has the same issue and we work thousands of ours fixing the inconsistencies. The pcb guy took the old mechanical footprint since it was not updated in the document, the fpga developer didn't consider the latest schematic change, the sw one took the wrong register description...and so on.
These are indeed 'trivial' issues which may be solved with more coordination, but if the part stress analysis is not considering the latest configuration consequences are the system will fail through the test campaign, if we are lucky, or on the field.
A more strict environment to produce documentation will ease the review phase and we will spend less ours with papers and more with development.
(sigh) I am envious! This suggests you have weeks that are NOT crazy??!
Understood. I've worked in safety related fields, gaming, medical, etc. The perceived value of paper is something that I "get".
Again, understood.
This is what my "lip service" comment attempts to address. Folks "know" the importance of the documents. But, are they willing to embrace what needs to be done to ensure their integrity/consistency??
E.g., "everyone" knows smoking is a substantial health risk. And, many smokers will willingly confess to "wanting to quit"; yet, don't take *any* (practical) steps towards this goal. Something else is always more important, more pressing, interfering with their plans, etc.
Ditto exercise, car maintenance, computer backups, etc.
E.g., the "inconvenience" of chemo/radiation therapy is obviously (?) considerably more (neglecting, for the moment, the likely outcome therefrom!) than the inconvenience of changing your lifestyle before that becomes an issue (likewise, the inconvenience of the FORCED lifestyle changes that a Ca diagnosis imposes!). Yet, acknowledged awareness of these "facts" still aren't enough to move people from the "lip service" they give ("I really should quit") to it.
Organizations *know* the value of testing BEFORE RELEASE for their products (hardware or software or other). And, the much higher costs associated with "missed errors" (customer dissatisfaction, support costs, warranty service, etc). Yet, BEYOND ACKNOWLEDGING THESE FACTS, many organizations have no qualms uttering nonsense like, "Yeah, I know we haven't tested it thoroughly. But, we're missing our market window! We'll fix it in the NEXT revision..."
This is the point I build on in the next comment:
So, the docs have to be finished and "correct". But, what commitment do staff (EVERYONE) have to making that happen "more effectively"? Your process suggests it is "someone else's job" to ensure the completeness and accuracy of these documents. Are the individual *authors* held accountable for their respective documents? Or, do they expect someone else to catch (and correct) their mistakes?
E.g., many years ago, a firm at which I was working embraced "MRP" (I guess the concept has undergone some name changes, subsequently). EVERYONE in the organization -- CEO to the folks on the factory floor -- went to school to understand the driving principles. And, were expected to EMBRACE them!
I.e., if asked how long it would take you to perform step 3 in the assembly process, you produced *a* number. And, you
*met* that number. If you *padded* it ("just to be safe"), you soon discovered that items that you managed to process in some time LESS than that had no place to be *stored*... the next step in the process had been designed to expect your step to take the time indicated. So, instead of giving yourself a "buffer" (padded estimate), you are now an obvious "problem" in the system -- items are piling up at your workstation (yet, the guy *after* you is working at his advertised pace!)
The "education" was to explain why these "numbers" were important. And, why a number that was too high was just as bad as a number that was too *low*. Unless everyone understood this, there would be these "process mismatches" at certain points in the overall process. (purchasing components too early meant you needed to warehouse components; finishing assembly too early meant you had to warehouse finished product; etc.)
It's just a very visible acknowledgement of where an organization's values lie. E.g., one guy doing "test" suggests you either have a very effective test/development/manufacturing process... *or*, are only giving token acknowledgement to that aspect of the business.
Again, you're missing my point. I understand (as I am sure "everyone" at your place of business does) that everyone is *affected*. But, is everyone *committed* to to solve the problem?
E.g., here's a solution: hire a staff that runs around picking up the pieces from all the prima donna's so they don't have to be concerned with those annoying little details! :> For someone very concerned about the problem AND affected by it, this is just as viable as forcing *them* to be more vigilant in their work. Or, putting in a system that reduces the chance of errors, etc.
They are "affected". But, are they willing to do what is *required* (which is "whatever YOU decide") to achieve those results? Are they willing to start exercising to lose weight? Or, would they rather just "take a pill" (and worry about side-effects later)?
But, you may find that people resent the stricter environment!
At one of the first firms that I worked, I ended up doing a stint testing military kit for a manufacturing subcontract we had been awarded. Part of the *process* (defined by the primary contractor which, in turn, was probably a requirement passed down by *their* customer) was to document every failure encountered in test.
This required filling out a form in which you described the symptoms of the problem/failure, your diagnosis/remedy as well as any "tricks" you employed to simplify the diagnosis. Attached to the form (which was a three or four part "carbon") was an envelope in which any "defective/removed" components were to be placed.
Finally, the form had provisions for you to indicate (in tenth hour increments) how long it took for you to identify the problem, repair and retest.
ALL OF THIS MAKES PERFECT SENSE -- now *and* then!
But, I'm pretty good at finding problems. Especially if I have been working with the same design for some time! You learn what can go wrong in the process as well as with the materials. So, I would typically test, diagnose, repair and RETEST a problem in less than
10 minutes -- 0.16 total time!
OTOH, it would take me several minutes to fill out the form, rescue the defective component, place it in the envelope, seal the envelope and file it away for delivery to client.
Despite knowing all this, I resented the "distraction" that all this paperwork represented. So, I started writing in another entry below the time metrics: "Time to fill out this damn form"!
Thankfully, my boss was smart enough to have a technician assigned to me for the dual purpose of:
- doing my paperwork
- learning how to do the testing that I was doing
There are all sorts of examples of folks bristling at imposed rules... even when they understand AND AGREE with their need.
What you need to figure out is: are all of these people ACHING for a better solution? And, how much are they willing to invest, individually, in that solution (vs. expecting it to be "bolted on" without affecting their current work practices)
ElectronDepot website is not affiliated with any of the manufacturers or service providers discussed here.
All logos and trade names are the property of their respective owners.