lecture: documentation

[timm]

Long doc is not good

• doc is effort
• "I have made this letter longer since I did not have time to make it shorter"

kinds of doc:

• what : point description
• how: common use cases
• why: top-level motivation
• why-not: choices within the design

examples good:

• Great WHY: Myers' intro to OOSD. nothing about objects for 30 pages. high level requirements. made Objects soundalike the only solution to all those issues
• how: common use cases: chapter 1 of "C". walk the. sold the language with lots of examples
• what: uml. the great uml failure: not used
  • uml on bnbad
  • uml i start, not end, of doc. all what. how how or why,
• unix doc project. synonspsis etc

doc generation tools docopt. pdoc3

don't get too excited about the tools. they are meerely the vans you draw on. once that is going its still up to you to write doc that makes sense to people.

doc is an explanation. good explanations reuse patterns known to the reader. different people have need different explanations. SE people have their patterns:

• koala blackboards
• lamp: (though the mean example). interesting case study, but not that since I fried it interns of LAMP, we could not journey thru decades of se developemnet
• lamp is a more general example of layers: lessons of layers (w.r.t MEAN and lamp)
• another famous layer pattern is model, view, controller (MVC)
• another famous layer patterns if data model dialog and DRY. hence the success of ruby. Ruby on Rails. its conceptual purity made it more palatable

lists of patterns:

• cognitive patterns, feature extraction (PIGE), match/select/act (first generation of AI).
  • btw, reasoning goes faster once they can break up the unknown into little pieces,
    • ideally, each of which can be reasoned about separately
• idioms .
  • python. context manager (what is opened must be closed. html. files), iterators
• design : got
• architectural (bigger). GOV
• product lines (e.g. watch) http://www.splot-research.org. e-commerce 235. note the cross tree constraints at the bottom
  • enter why not

btw, patterns harder in OO that in functional Programmers. evidence: 23 GOF patterns, rarely changed. functional programming: 10 patterns before breakfast

great example of good docs. spatial trees

• none of the bling we mentioned before
• so much to get me going
• you may not like the following example, cause it does not reuse a pattern you've seen before. but for me, this is off the charts. so bear with me.

finally, a note on doc and artifacts. so many artifacts. so few replicated. why? cause no on knows they exist! doc rules!

[timm]

TL;DR

Doco is effort. Hard effort

• "what" is not enough
• "how" makes people smile
• "why" makes them march
• "why not" is important
• patterns matter!
• doc general tools are the start, not the end, of doc

through forward: product line

• doc as specification and query. why document! specific in a. formal language
  • so much effort to write doc-- why not make the most of it
  • leads to to lots of what and a little why not (constraints),
  • not much how or why
• extra knowledge about code expressed in to some recursive structure with constraints
• theorem proving and requirements engineering
• test case generation

[timm]

som geratte doc genration tools

• markdown
• pandoc (that list of translators)
• mustache (more generally, its a template language). so much fun!
• Jekyll (more generally, its a site generation system)
• etc
• etc