ERD, Flowcharts and Other Documentation

FooLab

ERD, Flowcharts and Other DocumentationNortheast PHP Conference - August 11, 2012

Saturday, August 11, 2012

FooLabWhat It’s Not About

• Not a full analysis and design course

• Not a demo of modeling tools

• Not a detailed explanation of symbology

2


FooLabWhat It Is About

• What diagrams serve what purpose

• Tie diagrams together

• Real world examples

• More examples

3


FooLabAnna Filina

• PHP Quebec - user group

• ConFoo - non for profit Web conference

• FooLab Inc. - IT consulting

• I write code.

• I train and supervise programmers.

• I make recommendations.

4


FooLabWhy No Docs?

• Don't know where to begin

• It's boring

• There’s no point

• Get out of date

• Nobody reads them

5


FooLabThe Real Problem

• Don't understand diagrams

• Diagrams serve no purpose, not helpful

• Inadequate tools

6


FooLab

Conference Management Software


FooLabUse Case

8


FooLabER Diagram

9


FooLabER Diagram

9

0 or more(many)

1


FooLabER Diagram

10


FooLabER Diagram

10

Non-identifying

Identifying


FooLabER Diagram

11


FooLabData Flow Diagram

12



12

External entity



13



13

1 2 3 4 5 6

78



14


FooLabCommon Mistakes

15

• Data not stored.

• Black hole.

• Grey hole.

• Spontaneous generation.


FooLabFlowchart

16


FooLabFlowchart

16

Input

Output


FooLabMockups

17


FooLabMockups

18


FooLabFunction Reference

• Session

• bool isSelected()

• void mailConfirmation(), check logs

• bool saveVote($user, $vote)

• Automate tests of input/output.

19


FooLabSource Comments

• Inline comments // simple and short explanations

• /** * Commonly used above functions. * Can use annotations with phpDocumentor or other. */Descriptive blocks

• Comment when it’s fresh.

• Big functions with lots of comments = split function.

20


FooLab

Putting it all togetherA.K.A. “The Manual”


FooLabManual

• Define chapters. Example:

1. Scope (Use Cases)

2. Database (ERD)

3. Processes (DFD + Flowchart)

4. Mockups (later screenshots)

5. Classes + usage

22


FooLabManual

• Write topics in bullet point

• Add diagrams

• Write paragraph under each bullet

• Move topics and chapters around

• Fill in with details

23


FooLab

How much to write?


FooLabApplication Complexity

25

Grandma’s recipes

vs Facebook


FooLabApplication Complexity

25

More docsLess docs

Grandma’s recipes

vs Facebook


FooLabSecurity Requirements

26

Grandma’s recipes

vsIAFIS

fingerprints


FooLabSecurity Requirements

26

Grandma’s recipes

vsIAFIS

fingerprints

More docsLess docs


FooLabFinancial Impact

27

Grandma’s recipes vs

Forex currency trading


FooLabFinancial Impact

27

Grandma’s recipes vs

Forex currency trading

More docsLess docs


FooLabTeam Size

28

Yourself vs 20 devs


FooLabTeam Size

28

Yourself vs 20 devs

More docsLess docs


FooLabTeam Proximity

29

Same office

vs Remote


FooLabTeam Proximity

29

Same office

vs Remote

More docsLess docs


FooLabGood Documentation

• Makes your software easier to build and maintain

• Makes your team more effective

• Discover new features before implementation

30


FooLab

Mind MapsSaturday, August 11, 2012

FooLab

Systems Analysis and Design and/or UML book


FooLabNext Steps

• I will tweet the slides: @afilina

• Please leave feedback: http://joind.in/6838

33


http://joind.in/6838

http://joind.in/6838

FooLab

Ask me which software I use.


FooLab

Ask me which software I use.

astah, BalsamiqSaturday, August 11, 2012

ERD, Flowcharts and Other Documentation

Technology

Transcript of ERD, Flowcharts and Other Documentation