ERD, Flowcharts and Other Documentation

ERD, Flowcharts and Other Documentation

Documentation is much more than just commenting on code. It can be a lot more fun, too. Learn what types of documentation are useful, when it is appropriate to use documentation, and how to write it. Through real-world examples, I will teach you how to create meaningful, helpful documentation not only for posterity but also to guide you in your development efforts.

B3b2139e4f2c0eca4efe2379fcebc1c5?s=128

Anna Filina

March 22, 2017
Tweet

Transcript

  1. 2.

    What It’s Not About • Not a full analysis and

    design course. • Not a demo of modelling tools. • Not a detailed explanation of symbology.
  2. 3.

    What It Is About • Which diagrams serve what purpose.

    • Tie diagrams together. • Real world examples.
  3. 5.
  4. 6.

    Why No Diagrams? • Don't know where to begin. •

    It's boring. • Get out of date. • Nobody reads them. • There’s no point. • Lean and mean.
  5. 8.

    The Real Problem • Don't understand diagrams. • Diagrams serve

    no purpose, not helpful. • Mistake diagrams for waterfall model. • Inadequate tools.
  6. 10.
  7. 17.

    Common Mistakes • Data not stored. • Black hole. •

    Grey hole. • Spontaneous generation.
  8. 19.
  9. 20.
  10. 21.

    Function Reference • Session ◦ bool isSelected() ◦ void mailConfirmation(),

    check logs ◦ bool saveVote($user, $vote) • Automate tests of input/output.
  11. 22.

    Source Comments • // Simple and short explanations. • /**


    * Document the "why" more than the "what".
 */ • Comment when it’s fresh. • Big functions with lots of comments = split function. • Better naming > comments.
  12. 24.

    Manual • Define chapters. Example: 1.Scope (Use Cases) 2.Database (ERD)

    3.Processes (DFD + Flowchart) 4.Mockups (later screenshots) 5.Classes + usage
  13. 25.

    Manual • Write topics in bullet point. • Add diagrams.

    • Write paragraph under each bullet. • Move topics and chapters around. • Fill in with details.
  14. 32.

    Good Documentation • Makes your software easier to build and

    maintain. • Makes your team more effective. • Discover new features before implementation.
  15. 34.

    Takeaways • Systems Analysis and Design and/or UML book. •

    Get professional software, like Astah. • Diagrams are part of the process, not extra work. • Good diagrams increase dev speed and software quality.