You're about to create your best presentation ever

Documentation Powerpoint Template

Create your presentation by reusing a template from our community or transition your PowerPoint deck into a visually compelling Prezi presentation.


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:*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!)


Transcript: Person-First Terminology: Focuses on the person rather than the disability. Reasons for Documentation Provides update on patient/client treatment plan. Types of Documentation Terminology Other Elements of Documentation Resources Documentation Elements to include in a discharge note: Services Received by the Patient/Client Client's Responses to RT Treatment Plan Remaining Problems or Concerns Plan for Postdischarge According to Stumbo & Peterson (2009), rationale for documentation are: Assurance of Quality Services Facilitation of Communication among staff Professional Accountability and Self- Regulation Compliance with Administrative Requirements Agency Administration Corporation & Multi-facility Agencies Accreditation Agency Third- party payers Provision of Data for Quality Improvement/ Efficacy Research Principles of Quality Documentations Importance of Documentation Melina M. Rojas Florida International University Progress Notes Documentation are "written records" on: actions taken for the patient/client with patient/client by the patient/ client Main Idea: "If it's not in writing, it didn't happen" (Stumbo & Peterson p. 300) Discharge Documentation Reasons: Official legal Records It verifies the "process" that happens with and to clients in order to achieve measurable and predictable outcomes (Stumbo & Peterson p. 300). Provides a check and balance for TRAM (Therapeutic Recreation Accountability Model) Goals Objectives Condition, Behavior, and Criteria Client Management: Regards to individual patient/client outcomes Examples: assessments, treatment/ program plans, progress notes, discharge/referral plan Program Management: Regards to groups of patients/clients, administrative, supervisory, or programmatic records Examples: Comprehensive Program Plan (CPP), Specific Program Plan (SPP), Policies, Procedures, TR written plan of operations What is documentation? Stumbo & Peterson (2009) referred to the 3 C's of good charting: Consistency Conciseness Clarity

Now you can make any subject more engaging and memorable