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
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!
Long doc is not good
kinds of doc:
examples good:
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:
lists of patterns:
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
finally, a note on doc and artifacts. so many artifacts. so few replicated. why? cause no on knows they exist! doc rules!