Using Github for Product Documentation

A product is a labor or expertise, experience, and love, and the files are the manifestation of all.

As such, it should be:

• Complete: Everything about a product should be in one place.
• Clear: You should be able to tidy up, without deleting or losing anything.
• Accountable: Everything ever done, should be attributable to someone.
• Secure:  Who has access to change files can be controlled at any time.

General Rules

1. Stop using attachments and shared drives. Git allows your own copy to be controlled, and an automated way to transfer between team members.
2. Use shared documents like google sheets only for live editing. Once firmed up, put them into Git.
3. Commit early and often. It is always easier to redo and undo when the atomic pieces are small.
4. Recognize that commits serve as a notification of work done, allowing better tracking than time sheets and reporting with almost no effort. What did you commit today?
5. Keep work in progress (WIP) on a branch until it is working and ready to show to other team members.
6. Use Markdown instead of Word docs for any internal documentation. It has just enough formatting to be useful, but not so much as to distract.

Organization

You can use github for all files, not just software. One repo is workable for some projects, but if your process has clear definition between hardware and software, sometimes several repos is more efficient.

Hardware

1. Keep Design and Build files separate, so that Build can be released to manufacturers with a need to know basis.
2. Use OS level tools like TortoiseGit or Sourcetree to manage files for tools tat do not support revision control.
3. Use Tags to mark versions that were realized.

Software

1. Keep Source, Docs, and Inspections in directories.
2. Use .gitignore file to exclude generated files
3. Use Tags to mark released versions for test or production

Controlling complexity and quality

1. Assume the master branch is production, merging to master becomes a stamp of approval.
2. Create a branch for each change, and push the branch, then merge them with a pull request - a process known as flow. This only takes a few seconds, but makes it possible to de-tangle changes.  SourceTree by Atlassian is really good at making this easy to see what you are doing.
3. Always stage to before release. Ideally a second person reviews all changes before merging.  But even if it;s just one person, it has shown an effective way not to introduce errors or unplanned changes.
4. For all tests you conduct, create some artifact file (text, screenshot, etc) and put in Tests, and Commit it at the time you run the test. This way we know what was tested, and what code it was tested on.  You can use your commit message to explain your interpretation of the test.

References: