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
Nobody reads it.
When you need it,
it doesn't exist.
Nobody writes it.
is a habit.
Documentation should be a part
of your organization's
Sources of Documentation
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:
- Training materials.
- Manuals/reference materials.
- When you're delivering it:
- Delivery of finished product.
- Maintenance & ongoing development.
- Database - Storage, tables, views, relations.
- UML diagrams.
Everything that you produce as you design and structure the product.
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.
Everything your team produces during the process of developing the project.
- Task lists/boards.
- Progress reports.
- Team messages (Slack).
- Structural elements (classes, interfaces, etc.)
- Scripts and queries.
Code has inherent documentation properties.
- Demonstrates structure.
- Demonstrates functionality.
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.
Make note of anything unusual/exceptional (hacks, workarounds, &c).
You're using a source control/management tool like Git, right?
Of course you are.
- 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.
- Quick-Start Guides
- Training Materials
+ Depth -
it all go?
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.
- Support tickets.
- Bug reports.
- Requests for further development.
Developing a Culture
- 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.
By Jay Bienvenu