The BIG PICTUREThe BIG PICTUREProject Technical Project Technical

Documentation GuidelinesDocumentation Guidelines

www.folio3.com@folio_3

Folio3 – OverviewFolio3 – Overview

www.folio3.com @folio_3

Who We Are

We are a Development Partner for our customers

Design software solutions, not just implement them

Focus on the solution – Platform and technology agnostic

Expertise in building applications that are:

Mobile Social Cloud-based Gamified

What We Do Areas of Focus

Enterprise

Custom enterprise applications

Product development targeting the enterprise

Mobile

Custom mobile apps for iOS, Android, Windows Phone, BB OS

Mobile platform (server-to-server) development

Social Media

CMS based websites for consumers and enterprise (corporate, consumer,

community & social networking)

Social media platform development (enterprise & consumer)

Folio3 At a Glance Founded in 2005

Over 200 full time employees

Offices in the US, Canada, Bulgaria & Pakistan

Palo Alto, CA. Sofia, Bulgaria

Karachi, Pakistan

Toronto, Canada

Areas of Focus: Enterprise Automating workflows

Cloud based solutions

Application integration

Platform development

Healthcare

Mobile Enterprise

Digital Media

Supply Chain

Some of Our Enterprise Clients

Areas of Focus: Mobile Serious enterprise applications for Banks,

Businesses

Fun consumer apps for app discovery,

interaction, exercise gamification and play

Educational apps

Augmented Reality apps

Mobile Platforms

Some of Our Mobile Clients

Areas of Focus: Web & Social Media Community Sites based on

Content Management

Systems

Enterprise Social Networking

Social Games for Facebook &

Mobile

Companion Apps for games

Some of Our Web Clients

www.folio3.com @folio_3

The BIG PICTUREThe BIG PICTUREProject Technical Project Technical

Documentation GuidelinesDocumentation Guidelines

Quality Issues

Missing the “big picture”

No formal guidelines for the functional scope

Missing tracks on code commits/check-ins

Others …

Software Documentation Documentation is an important part of the software engineering

process.

Project Specifications/Requirements

Statements that identify attributes, capabilities, characteristics

or qualities of a system. This is the foundation for what shall be or

has been implemented.

Architecture/Design

Overview of software. Includes relations to the environment

and the construction principles to be used in design of software

components.

Software Documentation (Cont.) Technical

Documentation of code, algorithms, interfaces and APIs.

End User

Manuals for the end-user, system administrators and support staff.

Marketing

How to market the product and analysis of the market demand

At Folio3 the focus for developers should be on:

Architecture/Design

Technical documentation

On-the-go documentation inside code & during check-in

Folio3 Initiative

Developers are responsible for

Level 0: Source Code Self Documentation:

Comments

Level 1: Module Functional Scope Documents

Level 2: Overall Software Architecture Design

Level 3: Functional Specifications

Level 0: Source Code Self Documentation: Comments Code check-in comments - Mandatory

Defines Bugs fixes with Bug ID Feature/changes with feature/change story ID

File level comments - Mandatory Defines

Constituents Code distribution license Contributor names and timestamp

Class level comments - Mandatory Defines

Purpose Responsibilities Dependencies/Requirements

(Cont.)Level 0: Source Code Self Documentation: Comments Method level comments - Mandatory

Defines Purpose Arguments definition Return value definition Dependencies/Requirements (where applicable)

Algorithm level comments - Mandatory Defines

Steps declaration & their brief description Branch level comments - Mandatory

Defines Description on the condition that will branch on "if .. then", and on

"else"

(Cont.)Level 0: Source Code Self Documentation: Comments Other comments - Optional

Descriptions for important variables, objects Descriptions for essential calls

API Documentation - Optional Auto generated using the IDEs or document creator tool like

doxygen, etc.

Level 1: Module Functional Scope Module Brief Functional Specs – Mandatory

Should not be more than 3-4 pages. Defines:

Problem/Purpose statement

The requirements scope [OPTIONAL] - What is required by the customer?

Functional scope [OPTIONAL] - What is the functionally needed to fulfill the

above requirements?

Description of module items - Classes, ADTs, Functions, DB/Tables

UML Diagrams

Class diagram - Mandatory

Activity diagram - Optional

ER Diagram - Mandatory

Level 2: Overall Software Architecture Design Overall Software Design Specs - Mandatory

UML Diagrams

Overall Class Diagram (Optional) - Can be reverse engineered in

the end

Use Case diagram (Optional)

Component Diagram (Optional)

Package Diagram (Optional)

Deployment Diagram (Optional)

Data Flow Diagram (Optional)

Overall ER Diagram - Mandatory

Level 3: Functional Specifications

Feature Specifications

Change Specifications

Folio3 Requirements At least up to level 1

Means

Level 0: Source Code Self Documentation: Comments

Level 1: Module Functional Scope Document

Level 1: Module Class Diagram

Level 1: Module ER Diagram

In some cases, also the mandatory items from level 2

Means

Overall software design specs

Overall ER diagram

When to do Documentation?

Level 0 - Alongside coding / development.

Comments writing should not be scheduled as a later task.

They are often forgotten or left behind if scheduled

later.

Level 1 – At the start of module development

Should be used as guidelines by the developer.

Level 2 - Any time in the development life cycle

Level 3 - Before start of the development

Folio3 Documentation Life Cycle

Folio3 Documentation Life Cycle

De

v L

ea

d

Developers

Arc

hite

ctD

eve

lop

ers

Ma

na

ge

r

Requirement Specification

document

Level 2: Overall software design

specs

Level 2: Overall ER diagram

Level 1: Module Breif function specs

Level 1: Module Class diagram

Level 1: Module ER diagram

Level 1: Module Activity diagram

Level 2: Overall class diagram

Change Specification

document

Level 0: Source file comments

Level 0: Source commits/check-in comments

Level 2: Overall class diagram

Level 0: Generate/

Maintain API documentations

Mandatory Documentation Task

Optional Documentation Task

What tools should be used? IDEs

Can auto generate:

Class diagrams

Component diagrams

MS Visio

Can be used to create:

All UML diagrams

Data flow diagrams

ER diagrams

MS Word

Can be used for:

Specs and scoping documentations

Enforcement & Monitoring Estimators

MUST include / reserve some hours for documentation (till

Level 1 at least)

Managers and Tech / Dev Leads

Must make sure that they have all the required mandatory

documentation

AG

Must conduct Periodic (Quarterly) audits for each project

Contact

For more details about our services, please get in touch

with us.

contact@folio3.com

US Office: (408) 365-4638

www.folio3.com