dita spaghetti - recipes for documentation disasters
DESCRIPTION
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.TRANSCRIPT
![Page 1: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/1.jpg)
cooked up by Jang F.M. Graat
recipes for documentation disasters
![Page 2: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/2.jpg)
who’s cooking today ?
Jang F.M. Graat
DITA philosopher, tech writer & trainer, psychologist
Self-employed
Likes spaghetti, but not in the office
![Page 3: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/3.jpg)
guess who’s here for dinner tonight ?
![Page 4: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/4.jpg)
we’re out of supplies !
![Page 5: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/5.jpg)
everyone likes spaghetti, don’t they ?
![Page 6: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/6.jpg)
![Page 7: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/7.jpg)
reusability by jumps, goto’s and function calls
![Page 8: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/8.jpg)
![Page 9: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/9.jpg)
you never know what the user will need...
![Page 10: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/10.jpg)
pull one and you’ll pull them all
![Page 11: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/11.jpg)
famous program: Dr Watson
![Page 12: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/12.jpg)
everything is hidden under the GUI
![Page 13: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/13.jpg)
![Page 14: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/14.jpg)
beg, steal, and copy before you write
![Page 15: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/15.jpg)
![Page 16: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/16.jpg)
works if your products never change
![Page 17: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/17.jpg)
do you remember where all the copies are ?
![Page 18: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/18.jpg)
no more copies - only one source
![Page 19: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/19.jpg)
write in topics, build from maps
![Page 20: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/20.jpg)
how far can you afford to go ?
![Page 21: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/21.jpg)
any identifiable target is available
![Page 22: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/22.jpg)
![Page 23: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/23.jpg)
edit one and you’ll change them all
![Page 24: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/24.jpg)
do you know where all the conrefs are ?
![Page 25: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/25.jpg)
![Page 26: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/26.jpg)
separate writing from using
![Page 27: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/27.jpg)
all changes are made here
![Page 28: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/28.jpg)
live building blocks, not dead documents
![Page 29: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/29.jpg)
only conrefs - no writing allowed
![Page 30: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/30.jpg)
not meant for publication
![Page 31: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/31.jpg)
task
steps
step
step
step
step
step
step
step
step
step
step
step
step
step
step
step
step
step
step
warning
warning
caution
caution
notice
notice
supply
supply
supply
condition
condition
condition
closereqs
condition
condition
prelreqs
warning
caution
supply
condition
![Page 32: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/32.jpg)
conrefs always point in the same direction
![Page 33: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/33.jpg)
where is your stuff being used ?
![Page 34: DITA Spaghetti - Recipes for Documentation Disasters](https://reader037.vdocument.in/reader037/viewer/2022110302/5456494baf79597b578b5129/html5/thumbnails/34.jpg)
save copies of dead documents, just in case...