3 ms·

The same should be said for engineering design docs tbh

serf 3y ago
absolutely disagree. an engineering design document is about information retrieval, not education. It's not made to entertain or educate about new concepts, it's made to be terse and rigidly structured for the sake of aiding the work of the reader and to provide reliable information recall methods for those reading it. I don't want to know what 'problems are worth attacking' when reading a design document, I want to know what tolerance criteria the hole on the left flange needs to meet. There is more wiggle-room for artistic expression when we're talking about analytical papers like feasibility and failure analysis. It doesn't belong in the design phase. It creates confusion and ambiguity for the reader often, and those two things need not be introduced into design more than they already exist.
- Jensson 3y ago
  > It's not made to entertain or educate about new concepts, it's made to be terse and rigidly structured for the sake of aiding the work of the reader and to provide reliable information recall methods for those reading it. That goes for math papers as well. Both needs to be understood by juniors, both are used by experts for lookup and work.
- eternityforest 3y ago
  I might want to know why the hole on the left flange needs such insane tolerance though. Maybe it's not relevant in a specific version, or maybe I have an idea for how to solve the issue so it can be made cheaper, etc. Maybe it's absolutely integral to the whole application and I should stop wasting my time trying to make a printed PLA version, etc.
constantcrying 3y ago
Absolutely not. Engineering design docs should be terse and to the point. Documentation is not a medium where you want to tell a story, because that makes it instantly much less usable, since people will read it at random parts to attain specific information.
- vaylian 3y ago
  Maybe we have different ideas about what a "story" is, but stories are about defining a context and a progression from that context to a more advanced state. You can use technology in ways that the inventors never intended, but most of the time you want to know in which context the technology has been developed and which problems it can solve. That is why it makes sense to have stories in technical documentation.
  - constantcrying 3y ago
    >but stories are about defining a context and a progression from that context to a more advanced state. Exactly. Starting a story 80% in makes it nonsensical. If your engineering docs are nonsensical if you open them at 80% you have failed as a technical writer. >most of the time you want to know in which context the technology has been developed and which problems it can solve. ABSOLUTELY NOT. Imagine your dish washer manual going over the history of dish washers interspersed with comments about how it functions. That would be insane, useless and unreasonable.

serf 3y ago

absolutely disagree. an engineering design document is about information retrieval, not education. It's not made to entertain or educate about new concepts, it's made to be terse and rigidly structured for the sake of aiding the work of the reader and to provide reliable information recall methods for those reading it. I don't want to know what 'problems are worth attacking' when reading a design document, I want to know what tolerance criteria the hole on the left flange needs to meet. There is more wiggle-room for artistic expression when we're talking about analytical papers like feasibility and failure analysis. It doesn't belong in the design phase. It creates confusion and ambiguity for the reader often, and those two things need not be introduced into design more than they already exist.

Jensson 3y ago
> It's not made to entertain or educate about new concepts, it's made to be terse and rigidly structured for the sake of aiding the work of the reader and to provide reliable information recall methods for those reading it. That goes for math papers as well. Both needs to be understood by juniors, both are used by experts for lookup and work.
eternityforest 3y ago
I might want to know why the hole on the left flange needs such insane tolerance though. Maybe it's not relevant in a specific version, or maybe I have an idea for how to solve the issue so it can be made cheaper, etc. Maybe it's absolutely integral to the whole application and I should stop wasting my time trying to make a printed PLA version, etc.

constantcrying 3y ago

Absolutely not. Engineering design docs should be terse and to the point. Documentation is not a medium where you want to tell a story, because that makes it instantly much less usable, since people will read it at random parts to attain specific information.

vaylian 3y ago
Maybe we have different ideas about what a "story" is, but stories are about defining a context and a progression from that context to a more advanced state. You can use technology in ways that the inventors never intended, but most of the time you want to know in which context the technology has been developed and which problems it can solve. That is why it makes sense to have stories in technical documentation.
- constantcrying 3y ago
  >but stories are about defining a context and a progression from that context to a more advanced state. Exactly. Starting a story 80% in makes it nonsensical. If your engineering docs are nonsensical if you open them at 80% you have failed as a technical writer. >most of the time you want to know in which context the technology has been developed and which problems it can solve. ABSOLUTELY NOT. Imagine your dish washer manual going over the history of dish washers interspersed with comments about how it functions. That would be insane, useless and unreasonable.