Random Acts of Architecture

Tales of an architect trying to bring order to the chaos that is modern information technology.

Tag Archives: Wiki

In Defense of Documentation

Anyone who has spent a modicum of time working with software developers learns that developers hate creating designs, use cases, “readmes”, code samples and similar technical documentation. Agile proponents point to the “working software over comprehensive documentation” principle and Lean proponents claim documentation is “waste” since it does not directly contribute to the finished product or customer value.

They have a point. Writing clear, understandable documents is hard and it takes time away from coding. Keeping them up-to-date when inevitable changes occur is similarly time-consuming, particularly large changes or redesigns. Consequently, many stop asking for documentation, exacerbating poor or absent documentation. Many developers argue “code is documentation”. It is always up to date and developers had to work to understand it. Why shouldn’t everyone else?

However, saying “code is the only documentation” is a fallacy. Well written and designed code and indicative automated tests can be good documentation but every project includes code the developers are not proud of. Software developers often think of themselves coding like athletes lining up for a race at the Olympics. They have spent years training and are lining up to compete under perfect conditions. However, frequently code is written when developers are tired, stressed or unfamiliar with the problem or tools and this produces less correct and readable code.

Also, and arguably more important, developers are not the only audience for technical documentation. QA (testers), localization, management and documentation writers (those that write the manuals and non-technical documentation) all need technical information about the product and usually cannot read code, at least not well enough to get the information they need time efficiently. Developers new to the product also need a starting point.

Part of the problem is that documentation, particularly in larger organizations, consists of word processed documents or E-mail. E-mail in particular is a poor choice since it is only available to the recipients and often gets lost. An internal Wiki is a better choice, since most maintain a change history, have centralized storage making the latest version easier to find, support access control, provide auditing and can notify users of changes. Wikis are not perfect, however, since their storage formats are often proprietary and they often lack features of modern word pressing tools.

Wikis also encourage splitting documentation from large, monolithic documents into smaller sections. Care must be taken to ensure consistency and information is easy to find but most Wikis support free text searches. This fits better into the Agile and Lean methodologies, where smaller documents are delivered when needed rather than complete documentation delivered up front.

Writing documentation forces developers to identify and empathize with their customers or other developers, encouraging them to simplify the product’s design, user interface, installation and/or configuration. Some techniques, such as Documentation Drive Development and Readme Driven Development, encourage starting from the documentation for this reason.

It seems that literacy has become a skill in the software development industry. We have fooled ourselves into thinking that developers are only productive if they are writing code and poor documentation is acceptable. As Albert Einstein said “If you can’t explain it simply, you don’t understand it well enough.” Writing documentation forces developers out of their warm, cosy technical silos and back into the user world, reaquainting themselves with the problems the software is trying to solve.

Working Remotely and Successfully

A software architect is a difficult role at the best of times, particularly when working in a different office, time zone or country to the development team, other architects or management. In this case, architects miss the “water cooler” and “hallway” conversations and, unfortunately, “out of sight” is often “out of mind”. Much of what follows applies to non-software architect positions, too.

To be successful, remote architects must first create an environment where they are involved. A regular 1am team meeting on Saturday, for example, is neither sustainable nor fair. The team and its management need to adjust. Share minutes or notes for those that cannot attend meetings, too.

Remote architects must use meeting time effectively. They must know what information they need, who they are going to ask and follow it up afterwards. Regularly ask what team members are doing, such as training, travelling or talking to customers. Make time for small talk and rapport building, too.

Apply this to wider communications, too. Move away from E-mails for distributing documents and move to a common repository, like SharePoint or a Wiki so everyone can see what others are working on in addition to helping with versioning, auditing and knowing where the latest version is, and use an approved instant messaging system. When communicating, use a communication mechanism that targets the widest appropriate audience, such as a Wiki, and send notifications or links via traditional mechanisms, like E-mail.

Video conferencing is not as useful as many would claim. Skype and similar products suffer from the lower bandwidth and higher latency of international Internet connections. Professional telepresence systems like HP Halo are like being in the same room but can be difficult with people in different time zones or those that live or work away from the office.

Ensure the team travels to a central location for face-to-face meetings several times a year, too. If the organization cannot afford to bring important team members together for face-to-face meetings, an organization cannot afford to have remote employees. The critical aspect is not the meetings but the lunches, the drinks in the bar afterwards and relationship building, something video conferencing lacks.

During this “non-work” time, identify common interests with other team members, such as sport or similar aged children, and share them. Add the human element back into the team. As a previous workmate of mine once said, “You need to build a relationship before you can do business“.

Remote architects must recruit allies. Architects should talk regularly with their management, ensuring they understand their wants and needs, including up the management chain. Even the best communicators chronically under communicate with remote peers or subordinates, so remote team members must accept that their immediate manager cannot provide them all the information they require. They should talk to their peers and others outside their team, advertising their contributions and strengths, and create mutually beneficial relationships

Remote architects should do something interesting, professionally or not, and share it. Write up a few paragraphs and E-mail it to the team after attending conferences. Work on an open source project, join a local interest group or tutor a local college class.

Remote architects should make an effort to help others within the organization. For example, if someone wants a document proof read or reviewed, take the time to send intelligent comments through and carbon copy (CC) the rest of the team for visibility. Publicly give credit and thanks to others who help you with internal organizational reward systems, if they exist. Laugh at and remember other people’s jokes. Making people feel included will include the remote architect in the process.

Remote architects should get involved in projects outside their area or team. Many large organizations have discussion groups or committees, such as strategy or  review committees. Participating introduces the architect to new people, exposes his or her ideas to wider audiences and, once again, builds relationships.

Most importantly, remote architects should make an effort not to fall behind. They should do  training or otherwise become known as  experts in a field or a product, drawing them  into discussions about this area or product. Volunteer for new projects, particularly high-profile ones, and work hard to make them successful.

Ultimately, the success of a remote software architect is the architect’s responsibility. not the manager or team. This is the ultimate example of “managing your manager” and, if done right, allows an architect to enjoy a compromise of life style and professional success.
%d bloggers like this: