Jay Bienvenu
Software developer.
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
Documentation
By Jay Bienvenu
Documentation
- 927
