When doing the documentation for COHNERENT and Mark Williams C for the Atari ST followed this convention. See page 517 of http://www.nesssoftware.com/home/mwc/doc/coherent/manual/pdf... (pdf) for an example in the second paragraph of the 'date' command. (The entire manual is available at http://www.nesssoftware.com/home/mwc/manual.php in small pdf sections)
Slightly off topic: The manuals for COHERENT and the compiler products were, rather split into 'man' pages like Unix, were organized in a Lexicon. This enabled having one alpabetically-organized manual without separate sections. Thus, for the letter 'C', you can see 'c' as a command, followed by 'C language' as an overview, 'C Preprocessor -- overview', and further on 'calling conventions -- Definition'. This enabled adding much supporting material without exploding the page count.
root@thaumaturgy:/home/rob# Iptables
bash: Iptables: command not found
But, I agree that it can look a bit awkward. The usual fix is to use a different font and sometimes a different size or weight for text that's a command or programming idiom, and that's worked out pretty well for me too so far.