Devops for Growth

Use an Approach Inspired by Domain-Driven Design to Build Documentation That Evolves to Maximize Value Throughout Your Development Lifecycle

Software documentation can come to life, stay dynamic, and actually help you build better software. Writing for developers, coding architects, and other software professionals, Living Documentation shows how to create documentation that evolves throughout your entire design and development lifecycle.

Through patterns, clarifying illustrations, and concrete examples, Cyrille Martraire demonstrates how to use well-crafted artifacts and automation to dramatically improve the value of documentation at minimal extra cost. Whatever your domain, language, or technologies, you don’t have to choose between working software and comprehensive, high-quality documentation: you can have both.

·         Extract and augment available knowledge, and make it useful through living curation

·         Automate the creation of documentation and diagrams that evolve as knowledge changes

·         Use development tools to refactor documentation

·         Leverage documentation to improve software designs

·         Introduce living documentation to new and legacy environments 

TFSChangeLog automatically produces Change Log / Release Notes based on selected changeset range. TFS holds file version history via registered changesets and associated WorkItems. This exact information will be used for generating release notes. Configuration / Release manager can either use system data fields or custom fields for the purpose of generating release notes contents. Powerful XSLT 2.0 support for transforming data from raw XML format is provided out of the box which certainly opens up possibility to generate data in various formats. Support for XSLT 2.0 makes it very easy to apply filtering conditions for transformations output as required by the users. Supported command line interface can be used as part of scheduled task that can generate change log / release notes on a nightly basis.

I would like to add another point of view to some of the practical issues that I have faced in the field when it comes to producing Release Notes.

Following are the few examples where development team needs to adjust some contents for their release notes document where solution as provided by http://tfschangelog.codeplex.com will fit in very well.

1. Developer forgot to link WorkItem at the time of check-in.
2. Developer picked-up wrong WorkItem at the time of check-in.
3. Developer forgot to include appropriate information in the WorkItem record for their release notes.
4. Developer want’s to filter out some changes that should not appear in the release notes.
5. Developer forgot to link WorkItem at the time when he / she merged data between two different branches.
6. Different level of details are required for different target audience when it comes to release notes.
7. Some changes were rolled back due to test failures and were descoped from the current release.
8. Etc.

In such cases, it will nice to adjust few things post check-in for generating release notes on demand. I think that the solution provided by TFS ChangeLog application does exactly that.

It allows users to define their changeset range (timeline for generating release notes), based on which release notes are generate on demand. TFS ChangeLog also has command line version that allows users to generate release notes on a nightly basis via Windows Schedule task.

We continuously integrate. We continuously test and monitor. And perhaps, we also continuously deploy. So why do we suspend this essential continuity when it comes to documentation?

• 1 Techniques diverses
  • 1.1 Refactorisation de code
    • 1.1.1 Limitation
    • 1.1.2 Extension
  • 1.2 Documentation
    • 1.2.1 Dictionnaire du projet
    • 1.2.2 Documentation compréhensible
    • 1.2.3 Fake documentation
    • 1.2.4 « Time Stamp »
    • 1.2.5 « E-Backup »
  • 1.3 Design intensif
    • 1.3.1 Architecture de l'information
    • 1.3.2 Design Pipeline
• 2 Gestion de l'équipe
  • 2.1 Mise en place des méthodes agiles
  • 2.2 Programmation en binôme
    • 2.2.1 Limitations
    • 2.2.2 Extensions
  • 2.3 Auto-organisation de l’équipe
    • 2.3.1 Limitations
    • 2.3.2 Extensions
  • 2.4 Équipes distantes
• 3 Relation avec le client
  • 3.1 Implication du client
    • 3.1.1 Limitations
    • 3.1.2 Extensions
  • 3.2 Négociation de contrat
    • 3.2.1 Limitations
    • 3.2.2 Extensions
• 4 Conclusion
• 5 Références
• 6 Bibliographie

The out of the box report
By default the build report activity generates a report that is "changesets" centric, It lists all changesets the files and associated work items of each changesets. This might be good for a build report, but if you want a release note report, you probably would want it "work item centric", listing associated work item first and maybe list changesets without work item as Undocumented changes.

Changing the output
Luckily for us, we have the option to change the output. The BuildReport activity creates a xml file with the report data and then creates a html report by applying a xslt transformation. By supplying our own xslt file we can customize the output to suite us better, with some libations as we're bound to the data in the xml file.

The customized report

Even though the xml data isn't structured in the way we would prefer for our needs, actually the row xml data is also kind of changesets centric. But by using xslt it's still possible to extract a list of work items. By applying this xslt file https://skydrive.live.com/?cid=5D46CAE8C0008CF0&id=5D46CAE8C0008CF0!1058, the resulting report looks something like this.