Your SlideShare is downloading. ×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×

Saving this for later?

Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime - even offline.

Text the download link to your phone

Standard text messaging rates apply

DITA Spaghetti - Recipes for Documentation Disasters

1,196
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 …

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,196
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
14
Comments
0
Likes
0
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide

Transcript

  • 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