recipes for documentation disasterscooked up by Jang F.M. Graat
who’s cooking today ?Jang F.M. GraatDITA philosopher,tech writer & trainer,psychologistSelf-employedLikes spaghetti,but no...
guess who’s here for dinner tonight ?
we’re out of supplies !
everyone likes spaghetti, don’t they ?
reusability by jumps, goto’s and function calls
you never know what the user will need...
pull one and you’ll pull them all
famous program: Dr Watson
everything is hidden under the GUI
beg, steal, and copy before you write
works if your products never change
do you remember where all the copies are ?
no more copies - only one source
write in topics, build from maps
how far can you afford to go ?
any identifiable target is available
edit one and you’ll change them all
do you know where all the conrefs are ?
separate writing from using
all changes are made here
live building blocks, not dead documents
only conrefs - no writing allowed
not meant for publication
taskstep                        warning          prelreqsstep           warning      warning                  cautionstep ...
conrefs always point in the same direction
where is your stuff being used ?
save copies of dead documents, just in case...
make sure it does not get sticky...Jang F.M. Graat - jang@jang.nl
DITA Spaghetti - Recipes for Documentation Disasters
DITA Spaghetti - Recipes for Documentation Disasters
DITA Spaghetti - Recipes for Documentation Disasters
DITA Spaghetti - Recipes for Documentation Disasters
DITA Spaghetti - Recipes for Documentation Disasters
DITA Spaghetti - Recipes for Documentation Disasters
Upcoming SlideShare
Loading in …5
×

DITA Spaghetti - Recipes for Documentation Disasters

1,588 views

Published on

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.

Published in: Education
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
1,588
On SlideShare
0
From Embeds
0
Number of Embeds
4
Actions
Shares
0
Downloads
18
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

DITA Spaghetti - Recipes for Documentation Disasters

  1. recipes for documentation disasterscooked up by Jang F.M. Graat
  2. who’s cooking today ?Jang F.M. GraatDITA philosopher,tech writer & trainer,psychologistSelf-employedLikes 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 ?
  6. reusability by jumps, goto’s and function calls
  7. you never know what the user will need...
  8. pull one and you’ll pull them all
  9. famous program: Dr Watson
  10. everything is hidden under the GUI
  11. beg, steal, and copy before you write
  12. works if your products never change
  13. do you remember where all the copies are ?
  14. no more copies - only one source
  15. write in topics, build from maps
  16. how far can you afford to go ?
  17. any identifiable target is available
  18. edit one and you’ll change them all
  19. do you know where all the conrefs are ?
  20. separate writing from using
  21. all changes are made here
  22. live building blocks, not dead documents
  23. only conrefs - no writing allowed
  24. not meant for publication
  25. taskstep warning prelreqsstep warning warning cautionstep caution supplystep caution conditionstep notice stepsstep step notice stepstep step supply stepstep supply stepstep step supplystep condition closereqsstep condition condition conditionstep condition
  26. conrefs always point in the same direction
  27. where is your stuff being used ?
  28. save copies of dead documents, just in case...
  29. make sure it does not get sticky...Jang F.M. Graat - jang@jang.nl

×