Documentation
Transcript: Documentation is HARD Examples What's an instructive example? Would a diagram help? Documenting libraries As flask (think about the audience) def do_things(verbose=False): """Do some things. :param verbose: Be verbose (give additional messages). """ raise NotImplementedError Documentating Platform From the two perspectives: - so we understand what's going on (payments, calendaring) - so others can use our software (tom, frontend, future unhotels) - strategically important (Ultimately, platform is *just* a collection of external APIs, tied together by nameko.) @contextmanager def handle_insert(): try: yield except exceptions.CalendarNotFoundError: raise RPCKeyError('calendar id invalid.') except exceptions.ConflictingStateError as e: log.info(*e) # See docstring for ConflictingStateError raise Failure('conflicting state changes: {}'.format(e)) except exceptions.CalendarInsertError as e: raise Failure(e.message) Harder than coding Platform does not need prosaic docs. It is mostly a collection of APIs. Each service could also have a nice long docstring in the module. Internal docs can be written less comprehensively... (segue..) Documentation Unfortunate fact. Not an excuse Put this stuff inline. Otherwise, it goes out of date Or it's a PITA to code review There are no tools that easily link prose-docs to code (lighttable, we're still waiting) But every tool can collapse docstrings! Tips ~ George Orwell Why it matters How to write it Don't: """ Context manager that turns common calendaring exceptions into RPCKeyErrors or generic Failures. """ Do: """ Raise common calendar exceptions as RPC-compatible exceptions. """ For us: Much more nuanced. Is interlinking important? Does an argument need explaining? Should it be written inline or not? The things we're describing are inherently more complicated than the external API. A good model: Flask They have a "getting started" / "tutorial" type document, hyperlinked that augments a quite heavily documented API, which also includes links, documents arguments etc. But it's incomplete and judiciously applied. Obvious args are not explained. Objects/methods are not linked to unless it adds value to the reader i.e. developers. This is an art, not a science. HOW TO DO IT WHY IT MATTERS Again from the two perspectives: For others: - explicitly document external APIs - arguments, expected return values, valid ranges, default values, exceptions raised - tell a story. sphinx allows us to hyperlink our docs. this is amazing for external users All of this is a PITA for us to do. If it makes you feel better, reclassify the task as "writing our interface". It's not really documentation any more - it's an interface definition. Document: - RPC calls - Events (when fired, contents) - Models - Exceptions INTRO Don't describe intricacies of the code in the docstring. If something is particularly intricate and requires an english explanation, use an inline comment. If it is possible to cut out a word, always cut it out Use active not passive voice - usually more terse e.g. "I heard it through the grapevine", not "It was heard by me through the grapevine" A scrupulous writer, in every sentence that he writes will ask himself at least four questions, thus: What am I trying to say? What words will express it? What image or idiom will make it clearer? Is this image fresh enough to have an effect? And he will probably ask himself two more: Could I put it more shortly? Have I said anything that is avoidably ugly? Bonus: Writing docs makes you think about your code differently, which tends to improve it. If you can't explain *why* something happens, maybe it doesn't need to. NB. Sometimes a diagram is better than a paragraph. This is also documentation! Why bother? Help us undertstand our code (and new devs) Help others understand our code Different objectives. Different approaches. Words of Wisdom (ha!)
Prezi Present
Prezi Video
Prezi Design
