This presentation identifies problems with a reuse-based system and how to avoid turning this type of system into total documentation chaos (comparable to the well-known spaghetti code of some inexperienced programmers in the days before object orientation). It outlines some best practices to avoid unmanageable linking, and content referencing in an environment where links and conrefs are the coolest part of the deal.

1. recipes for documentation disasters
cooked up by Jang F.M. Graat

2. who’s cooking today ?
Jang F.M. Graat
DITA philosopher,
tech writer & trainer,
psychologist
Self-employed
Likes spaghetti,
but not in the office

3. guess who’s here for dinner tonight ?

4. we’re out of supplies !

5. everyone likes spaghetti, don’t they ?

7. reusability by jumps, goto’s and function calls

9. you never know what the user will need...

10. pull one and you’ll pull them all

11. famous program: Dr Watson

12. everything is hidden under the GUI

14. beg, steal, and copy before you write

16. works if your products never change

17. do you remember where all the copies are ?

18. no more copies - only one source

19. write in topics, build from maps

20. how far can you afford to go ?

21. any identifiable target is available

23. edit one and you’ll change them all

24. do you know where all the conrefs are ?

26. separate writing from using

27. all changes are made here

28. live building blocks, not dead documents

29. only conrefs - no writing allowed

30. not meant for publication

31. task
step warning
prelreqs
step warning warning
caution
step caution
supply
step caution
condition
step notice
steps
step step
notice
step
step step
supply
step
step supply
step
step step supply
step condition
closereqs
step condition condition
condition
step condition

32. conrefs always point in the same direction

33. where is your stuff being used ?

34. save copies of dead documents, just in case...

35. make sure it does not get sticky...
Jang F.M. Graat - jang@jang.nl