2 added 27 characters in body
source | link

What I've donelearned. (I tried a different order. I was wrong. This is the order in which things become relevant.)

  1. Put everything into source code control. Use something everyone has access to and start right now. No exceptions. No delays. No excuses.

  2. Create a QA/Test area that is totally separate from your personal "working" or "development" environment. At least a separate user id. Ideally on a separate VM.
    Completely separate. No possible overlap with your current working environment.

  3. Stop testing beyond unit test in your own working environment. Code and unit test you do "as yourself". All other testing (integration, performance, whatever) you do on the separate VM. Never test as yourself. Always test as a separate QA user. Ideally on a separate VM.

    "Works for me," is a bad thing to have to say to your team member(s). Very bad. You need to figure out what they're doing wrong. Several times a day.

  4. Plan to write down everything. Use a plain-text markup tool (RST or Markdown or something) so that all documentation is plain-text in the version control repository. A tool can create HTML pages (i.e., Docutils for RST) or PDF's or whatever seems best. Don't use proprietary document formats (i.e. MS-Word). They may not play well with some source-code control systems.

  5. The first things you need to write down are the following.

    • How to create a working development environment. When in doubt, create a Virtual machine and do the entire operation on that virtual machine. Be sure that the steps really work and the documentation is clear. Actual lines typed at the actual command line kind of clarity.

    • How to run the unit test suite. Again. Be sure that the instructions work and do not require thinking. "Type this:" "Confirm that:" kind of stuff. It's not that your team members are stupid. It's that you don't remember what you're assuming unless you write it all down.

    • How to run the integration test suite.

    Don't waste a lot of time describing the architecture or the design principles. You need to get someone up and running first. You can explain stuff later.

  6. The next things to document are the user stories. And the test cases that support those stories. And the data fixtures required for the test cases that support those user stories.

    You will be sharing this. It goes under source code control.

  7. Eventually, you can document the other 4 views.

    • Logical view is helpful stuff to document. Pictures are acceptable here. This tends to evolve rapidly, so don't spend time capturing the legacy information. Work out a way to cooperate with your team member(s).

    • Process view is often helpful. Depends on the overall application how important this is.

    • Development view -- modules, libraries, frameworks, etc. -- is often described informally. A picture might help, but it's notoriously hard to make this complete enough that someone can pick up a document and make heads or tails of it. Even long-established, very public projects have library documentation that is simply ignored. (Leading to a lot of Stack Overflow questions.)

      Besides being acceptable to be informal, this tends to change rapidly.

    • Deployment information. Servers. IP addresses. Database credentials. All that stuff must get written down. Eventually.

What I've done.

  1. Put everything into source code control. Use something everyone has access to and start right now. No exceptions.

  2. Create a QA/Test area that is totally separate from your personal "working" or "development" environment. At least a separate user id. Ideally on a separate VM.
    Completely separate. No possible overlap with your current working environment.

  3. Stop testing beyond unit test in your own working environment. Code and unit test you do "as yourself". All other testing (integration, performance, whatever) you do on the separate VM. Never test as yourself. Always test as a separate QA user. Ideally on a separate VM.

    "Works for me," is a bad thing to have to say to your team member(s). Very bad. You need to figure out what they're doing wrong. Several times a day.

  4. Plan to write down everything. Use a plain-text markup tool (RST or Markdown or something) so that all documentation is plain-text in the version control repository. A tool can create HTML pages (i.e., Docutils for RST) or PDF's or whatever seems best. Don't use proprietary document formats (i.e. MS-Word). They may not play well with some source-code control systems.

  5. The first things you need to write down are the following.

    • How to create a working development environment. When in doubt, create a Virtual machine and do the entire operation on that virtual machine. Be sure that the steps really work and the documentation is clear. Actual lines typed at the actual command line kind of clarity.

    • How to run the unit test suite. Again. Be sure that the instructions work and do not require thinking. "Type this:" "Confirm that:" kind of stuff. It's not that your team members are stupid. It's that you don't remember what you're assuming unless you write it all down.

    • How to run the integration test suite.

    Don't waste a lot of time describing the architecture or the design principles. You need to get someone up and running first. You can explain stuff later.

  6. The next things to document are the user stories. And the test cases that support those stories. And the data fixtures required for the test cases that support those user stories.

    You will be sharing this. It goes under source code control.

  7. Eventually, you can document the other 4 views.

    • Logical view is helpful stuff to document. Pictures are acceptable here. This tends to evolve rapidly, so don't spend time capturing the legacy information. Work out a way to cooperate with your team member(s).

    • Process view is often helpful. Depends on the overall application how important this is.

    • Development view -- modules, libraries, frameworks, etc. -- is often described informally. A picture might help, but it's notoriously hard to make this complete enough that someone can pick up a document and make heads or tails of it. Even long-established, very public projects have library documentation that is simply ignored. (Leading to a lot of Stack Overflow questions.)

      Besides being acceptable to be informal, this tends to change rapidly.

    • Deployment information. Servers. IP addresses. Database credentials. All that stuff must get written down. Eventually.

What I've learned. (I tried a different order. I was wrong. This is the order in which things become relevant.)

  1. Put everything into source code control. Use something everyone has access to and start right now. No exceptions. No delays. No excuses.

  2. Create a QA/Test area that is totally separate from your personal "working" or "development" environment. At least a separate user id. Ideally on a separate VM.
    Completely separate. No possible overlap with your current working environment.

  3. Stop testing beyond unit test in your own working environment. Code and unit test you do "as yourself". All other testing (integration, performance, whatever) you do on the separate VM. Never test as yourself. Always test as a separate QA user. Ideally on a separate VM.

    "Works for me," is a bad thing to have to say to your team member(s). Very bad. You need to figure out what they're doing wrong. Several times a day.

  4. Plan to write down everything. Use a plain-text markup tool (RST or Markdown or something) so that all documentation is plain-text in the version control repository. A tool can create HTML pages (i.e., Docutils for RST) or PDF's or whatever seems best. Don't use proprietary document formats (i.e. MS-Word). They may not play well with some source-code control systems.

  5. The first things you need to write down are the following.

    • How to create a working development environment. When in doubt, create a Virtual machine and do the entire operation on that virtual machine. Be sure that the steps really work and the documentation is clear. Actual lines typed at the actual command line kind of clarity.

    • How to run the unit test suite. Again. Be sure that the instructions work and do not require thinking. "Type this:" "Confirm that:" kind of stuff. It's not that your team members are stupid. It's that you don't remember what you're assuming unless you write it all down.

    • How to run the integration test suite.

    Don't waste a lot of time describing the architecture or the design principles. You need to get someone up and running first. You can explain stuff later.

  6. The next things to document are the user stories. And the test cases that support those stories. And the data fixtures required for the test cases that support those user stories.

    You will be sharing this. It goes under source code control.

  7. Eventually, you can document the other 4 views.

    • Logical view is helpful stuff to document. Pictures are acceptable here. This tends to evolve rapidly, so don't spend time capturing the legacy information. Work out a way to cooperate with your team member(s).

    • Process view is often helpful. Depends on the overall application how important this is.

    • Development view -- modules, libraries, frameworks, etc. -- is often described informally. A picture might help, but it's notoriously hard to make this complete enough that someone can pick up a document and make heads or tails of it. Even long-established, very public projects have library documentation that is simply ignored. (Leading to a lot of Stack Overflow questions.)

      Besides being acceptable to be informal, this tends to change rapidly.

    • Deployment information. Servers. IP addresses. Database credentials. All that stuff must get written down. Eventually.

1
source | link

What I've done.

  1. Put everything into source code control. Use something everyone has access to and start right now. No exceptions.

  2. Create a QA/Test area that is totally separate from your personal "working" or "development" environment. At least a separate user id. Ideally on a separate VM.
    Completely separate. No possible overlap with your current working environment.

  3. Stop testing beyond unit test in your own working environment. Code and unit test you do "as yourself". All other testing (integration, performance, whatever) you do on the separate VM. Never test as yourself. Always test as a separate QA user. Ideally on a separate VM.

    "Works for me," is a bad thing to have to say to your team member(s). Very bad. You need to figure out what they're doing wrong. Several times a day.

  4. Plan to write down everything. Use a plain-text markup tool (RST or Markdown or something) so that all documentation is plain-text in the version control repository. A tool can create HTML pages (i.e., Docutils for RST) or PDF's or whatever seems best. Don't use proprietary document formats (i.e. MS-Word). They may not play well with some source-code control systems.

  5. The first things you need to write down are the following.

    • How to create a working development environment. When in doubt, create a Virtual machine and do the entire operation on that virtual machine. Be sure that the steps really work and the documentation is clear. Actual lines typed at the actual command line kind of clarity.

    • How to run the unit test suite. Again. Be sure that the instructions work and do not require thinking. "Type this:" "Confirm that:" kind of stuff. It's not that your team members are stupid. It's that you don't remember what you're assuming unless you write it all down.

    • How to run the integration test suite.

    Don't waste a lot of time describing the architecture or the design principles. You need to get someone up and running first. You can explain stuff later.

  6. The next things to document are the user stories. And the test cases that support those stories. And the data fixtures required for the test cases that support those user stories.

    You will be sharing this. It goes under source code control.

  7. Eventually, you can document the other 4 views.

    • Logical view is helpful stuff to document. Pictures are acceptable here. This tends to evolve rapidly, so don't spend time capturing the legacy information. Work out a way to cooperate with your team member(s).

    • Process view is often helpful. Depends on the overall application how important this is.

    • Development view -- modules, libraries, frameworks, etc. -- is often described informally. A picture might help, but it's notoriously hard to make this complete enough that someone can pick up a document and make heads or tails of it. Even long-established, very public projects have library documentation that is simply ignored. (Leading to a lot of Stack Overflow questions.)

      Besides being acceptable to be informal, this tends to change rapidly.

    • Deployment information. Servers. IP addresses. Database credentials. All that stuff must get written down. Eventually.