4

What is the best practice and software you use to document change related document.

lso, how you prefer to document the changes in the project.

Let say, you got a requirement to make some changes in the project. How do you proceed?

  • Do you take the complete backup before processing. Will this backup be documented. If yes, then how?
  • How the change will be documented? Any template? How this will be shared between the peers?
  • What will be the content of the change request procedure?
  • Do you keep the affected code, queries etc in some folder/document?
Chris
  • 256
  • 1
  • 11
  • Are you asking about changes in code checkins? Or about maintaining a set of Release Notes like here: http://unity3d.com/unity/whats-new/unity-3.3 ? – Al Biglan May 19 '11 at 19:13

5 Answers5

6

Quite simply, use source control. To answer your questions specifically:

  1. If project(s) are not currently in source control, then start using Subversion (classic model) or Mercurial (distributed model) and put your project(s) in source control. Document by sending an email to management, editing a wiki, or writing up a simple document that explains how to access files in your source control repositories.
  2. Changes are documented automatically by source control. Every time you commit a change, provide a good comment that explains the changes being made and why.
  3. If someone requests changes, export history from the repository with svn log (Subversion) or hg log (Mercurial). You could write a script to parse the log output and pretty-print it in a desired format.
  4. Source control will track affected code. Database queries, if they are not directly in the code, should be put in files that are also stored in source control.
Matthew Rodatus
  • 7,551
  • 1
  • 28
  • 32
  • 3
    I'd actually recommend git over Mercurial just for the ease of branch per feature workflow but other then that agree. – ShaneC May 19 '11 at 20:36
5

In addition to Source Control, it is absolutely essential that you have a bug and feature tracking tool. If you can tie your bug tracking tool to your source control tool, even better.

Between the two tools, you will have all the documentation you will ever need. As long as you use them of course. Using them can be a little bit of a challenge as some will see it as "extra work".

www.fogcreek.com make a bug tracker and source control (FogBugz and Kiln) that are nicely tied together with little effort. They are both super easy to use.

Joel Spolsky did up a nice tutorial on using source control based on Mercurial. It's a great series, especially if you are new to source control. www.hginit.com

SLoret
  • 565
  • 2
  • 9
3

Managing Change is more than just using Source control. Source control is an absolute necessity even if there is no change in requirements. Whenever there is a requirement to 'change' something in the project you need to consider many things.

  • You need to analyze the impact of the suggested Change [like what all modules are affected due to this]
  • If the project is going under a fixed time structure then you need to analyze the additional efforts required to implement this change and get then same approved by the client.
  • Branching needs to be done in source control if necessary, Or else you can tag the files using some naming convention. You can avoid a simple backup here which will later get hard to manage.
  • The requirement document should track all the changes in chronological order. Requirement document changes can also be tracked under version control or any Document Management system as applicable to your work environment.

To Summarize based on your subquestions.

  • Do you take the complete backup before processing. Will this backup be documented. If yes, then how?
    • You can use Tags/Branches if using SVN,Manual Backups will be hard to manage
  • How the change will be documented? Any template? How this will be shared between the peers?
    • The Change should definitely be documented. If you don't plan to have a Change control management document then requirement document should contain version history and all document revisions should be under version control/Document management system.

  • What will be the content of the change request procedure?

    • Change request procedure will be like this
      • Client initiates change request.
      • Requirement document is updated.
      • Impact Analysis is done.
      • Additional efforts/scope/Costing is discussed and finalized.
      • Code is tagged/branched
      • Developers can mention the change control id as comments in code if needed.
      • All the above should be documented.

  • Do you keep the affected code, queries etc in some folder/document?

    • All the code will be available in Source control,They should be properly tagged.
Vimal Raj
  • 642
  • 1
  • 4
  • 13
1

First step: make sure you have a Change Control Board that represents all project stakeholders.

That ensures visibility of the proposed change, and the decision about the change.

Peter K.
  • 3,828
  • 1
  • 23
  • 34
  • 1
    +1 this was a real help in the larger teams that I have worked on. Smaller teams could do it too, but meetings would just be that much shorter. – JoshBaltzell May 19 '11 at 19:15
1

In the WikiEngine project, I built a small 'wiki application' that uses a folder with files for data and links/backlinks, which actually is a pretty good fit for committing into text-based version control systems like SVN or Git.

When making changes, I update any pages from the wiki, and commit/push them together with the changes in code.

Stijn Sanders
  • 193
  • 1
  • 8