Do not explain anything [in a how to guide] unless absolutely necessary. Offer links, but you do not explain crabs in a crab sandwich recipe. You can include flexibility and variations, but not explanations. Practical usability is more important than completeness. #PyConUK
-
Show this thread
-
"The most important thing to remember [from this talk] is that how to guides and tutorials are completely distinct."
#PyConUK1 reply 0 retweets 3 likesShow this thread -
In contrast, reference documentation is information-oriented. It is information-oriented. It does not tell you how to do things, it describes that which is the case. It should be austere and to the point, giving the reader only the facts.
#PyConUK1 reply 1 retweet 4 likesShow this thread -
What matters in a reference is structure, consistency, description, and accuracy. The only job is to describe, anything else is wasting people's time.
#PyConUK1 reply 0 retweets 4 likesShow this thread -
Explanations are background discussions that clarify and illuminate a particular topic. These are understanding-oriented. At this point you can finally give in to the temptation to using abstraction.
#PyConUK1 reply 1 retweet 4 likesShow this thread -
"Explanation is the only part of the material that you should be able to read in the bath"
#PyConUK1 reply 0 retweets 3 likesShow this thread -
Explanations are where you can make analogies, and put things into the bigger picture. There should be no instruction or technical description in explanatory documentation.
#PyConUK1 reply 0 retweets 3 likesShow this thread -
In summary, the four types: Tutorials: Learning-oriented. How-to guides: problem-oriented: Explanation: Understanding-oriented. Reference: Information-oriented.
#PyConUK2 replies 2 retweets 8 likesShow this thread -
Replying to @DRMacIver @_awbery_
TY for tweeting this series - I know nothing about Python nor about any other programming languages but I found those distinctions useful. I can apply this to anything! I used to write tutorials and the like for a web developing biz, and it was hard not to ram in too much info.
1 reply 0 retweets 2 likes
Yes, aren’t they great? Not dstinctions I had thought about at all before, but obvious once recognized.
-
-
Replying to @_awbery_ @DRMacIver
This reminds me, TY for RTing his tweet because I actually follow you, ha.
0 replies 0 retweets 1 likeThanks. Twitter will use this to make your timeline better. UndoUndo
-
Loading seems to be taking a while.
Twitter may be over capacity or experiencing a momentary hiccup. Try again or visit Twitter Status for more information.