Post History
If a reader follows a reasonable path1 through your documentation, there should never be a point where he's looking at something incomprehensible. This applies to text, code samples, diagrams...and...
Answer
#4: Post edited
by
Monica Cellio
·
2020-05-17T17:20:58Z (over 4 years ago)
trying to fix formatting of superscripts
If a reader follows a reasonable path<sup>1</sup> through your documentation, there should never be a point where he's looking at something incomprehensible. This applies to text, code samples, diagrams...and screen shots. Therefore, unless the structure of your document itself provides this (e.g. through section titles and a consistent format, like in a catalogue), you should always have some explanatory text before the screen shot to provide context.However, this principle applies to text too -- you don't want to have a page of text describing stuff that will only make sense after someone sees the screen shot, either. So in my experience the norm is: text that sets the stage, then the screen shot, then details that refer to the screen shot.This is true with or without figure numbers and captions.<sup>1</sup> At minimum (for non-reference doc), starting at the beginning and reading through. But also consider the case of someone who looks something up in the table of contents and jumps there, and, if applicable, the use of your documentation in online context-sensitive help.
- If a reader follows a reasonable path<sup>1</sup> through your documentation, there should never be a point where he's looking at something incomprehensible. This applies to text, code samples, diagrams...and screen shots. Therefore, unless the structure of your document itself provides this (e.g. through section titles and a consistent format, like in a catalogue), you should always have some explanatory text before the screen shot to provide context.
- However, this principle applies to text too -- you don't want to have a page of text describing stuff that will only make sense after someone sees the screen shot, either. So in my experience the norm is: text that sets the stage, then the screen shot, then details that refer to the screen shot.
- This is true with or without figure numbers and captions.
- <sup>1</sup> At minimum (for non-reference doc), starting at the beginning and reading through. But also consider the case of someone who looks something up in the table of contents and jumps there, and, if applicable, the use of your documentation in online context-sensitive help.
#3: Attribution notice added
by
System
·
2019-12-08T02:56:01Z (almost 5 years ago)
Source: https://writers.stackexchange.com/a/8166 License name: CC BY-SA 3.0 License URL: https://creativecommons.org/licenses/by-sa/3.0/
#2: Initial revision
If a reader follows a reasonable path<sup>1</sup> through your documentation, there should never be a point where he's looking at something incomprehensible. This applies to text, code samples, diagrams...and screen shots. Therefore, unless the structure of your document itself provides this (e.g. through section titles and a consistent format, like in a catalogue), you should always have some explanatory text before the screen shot to provide context. However, this principle applies to text too -- you don't want to have a page of text describing stuff that will only make sense after someone sees the screen shot, either. So in my experience the norm is: text that sets the stage, then the screen shot, then details that refer to the screen shot. This is true with or without figure numbers and captions. <sup>1</sup> At minimum (for non-reference doc), starting at the beginning and reading through. But also consider the case of someone who looks something up in the table of contents and jumps there, and, if applicable, the use of your documentation in online context-sensitive help.
#1: Imported from external source
by
System
·
2013-06-14T18:45:10Z (over 11 years ago)
Original score: 23