Documentation

 

Jay Bienvenu

July 11, 2018

Baton Rouge SS/DN User Groups

About Your Presenter

  • Recreational programmer for three decades.
  • Professional programmer for two decades.
  • Industries: Government, health, entertainment, &c.
  • Experience in both the Microsoft world and
    the open-source world.
  • Currently with NetShapers, working in PHP and MySQL.

Jay's Three Rules
of Documentation

Nobody reads it.

When you need it,
it doesn't exist.

Nobody writes it.

Documentation
is a habit.

Documentation should be a part
of your organization's
culture.
 

Sources of Documentation

Project Plans

Meeting Notes

Design

Code Comments

Tasks

Issues

Knowledge Base

Source Control

Commit History

Branches

Training Guides

Bug Reports

Support Tickets

Scope of Work

From the Beginning

Scoping, Planning & Design

Scope of Work

The formal agreement that specifies
all criteria of your contract
with the customer.

  • What you're producing:
    - Software.
    - Training materials.
    - Manuals/reference materials.
  • When you're delivering it:
    - Milestones.
    - Delivery of finished product.
    - Maintenance & ongoing development.

Design

  • Database - Storage, tables, views, relations.
  • Flowcharts.
  • UML diagrams.
  • &c.

Everything that you produce as you design and structure the product.

Vendor-Client

Communication

Everything that you produce as you meet and communicate with the client during the planning and development of the project.

  • Meeting notes.
  • Emails, text messages, phone calls.

Interoffice
Communication

Everything your team produces during the process of developing the project.

  • Task lists/boards.
  • Progress reports.
  • Team messages (Slack).

Code

  • Structural elements (classes, interfaces, etc.)
  • Scripts and queries.

 

 

Code has inherent documentation properties.

  • Demonstrates structure.
  • Demonstrates functionality.

Code Comments

Block comments for each structural element.

  • Brief description of why it exists.
  • Author, version/creation date.
  • Parameters, return type, exceptions.
  • Links to external information.

Inline comments for variables & operations.

  • Expected type returned by functions.
  • Exceptions that could be thrown.
  • Clarifications/explanations.

Make note of anything unusual/exceptional (hacks, workarounds, &c).

Source Control

You're using a source control/management tool like Git, right?
Of course you are.

  • Commits
  • Branches

Automated Testing

  • Demonstrates that the code works.
  • Demonstrates usage of structural elements.
  • Isolates functional elements from the project.
  • Provides an opportunity to demonstrate usage of the code in unusual situations.

Deliverables

  • Readmes
  • Quick-Start Guides
  • FAQs
  • Training Materials
  • Manuals

+ Depth -

Where does
it all go?

Knowledge Base

A repository of structured and unstructured data.

Consider using an integrated multimodal tool like GitHub or GitLab.

Have one knowledge base for your company and a separate or connected
knowledge base for each project.

Wikis are great for knowledge bases.

Customer Support
Maintenance &
Further Development

  • Support tickets.
  • Bug reports.
  • Requests for further development.

Developing a Culture
of Documentation

  • Digitize all content.
    - Type up hand-written notes.
    - Scan or take pictures of hand-drawn diagrams.
    - Use diagramming tools to make diagrams.
  • Use an issue tracker to record tasks and their progress.
  • Write readable code. Implement coding standards.
  • Use programming language features to augment & annotate structural elements & their interfaces.
  • Make software work for you.
    Find tools that work and use them.

Questions

Made with Slides.com