Happy new job notes

[wiredferret]

I'm walking through the tech docs internal documentation (no, I still don't have my software), and getting all excited. This is one of the most intentional and philisophical doc groups I have worked with (probably because I have specialized in people who need structure, not people who already have it).
Most writers are used to writing narrative

Comments

[omnifarious]

I agree with the sentiment, but there is one danger I see in task based documentation. I think one of the goals of documentation should be to encourage the user to adopt a mental model of the internal workings of the program that will tend to lead them to make correct guesses about its behavior when they do things that aren't in any documentation they've read.

I think it's the task of a good user interface to do this as well. The UI and the documentation should fit together to accomplish this goal.

The biggest danger I see in use-case based user interfaces or task oriented documentation is an abandonment of this principle. This will ultimately result in a program that frequently surprises the user with its behavior whenever the user deviates from one of the pre-planned scripts, and the user won't like using it.

[wiredferret]

True, and there is a document type that addresses the need to understand the overall scope and goal of the product.

[lexinatrix]

Just think! You could have requirements written in use case form, and they flow through implementation, test cases and straight into task-based help and reference docs. Wheee!

[wiredferret]

That is, in fact, sort of the theory. It's just wacky. Of course, being Agile, the test case is written before the implementation, so there's a chance I can finish almost simultaneously with the development.

[lexinatrix]

You live in heady, exciting times.

[toadnae]

Yay! Are they using DITA or just structured authoring? I'm currently in the throes of an article review of DITA and it is really interesting my brain. Sadly, there are very few jobs currently advertising DITA.

[wiredferret]

The plan is to transition to DITA within the next year. Part of the reason I got hired (I think) was my enthusiasm about this project.