Carlos Costa invited me to present my OSDOC'10 paper to his graduate students on open source software at ISCTE. The presentation took place in building ISCTE II, auditorium B203, Saturday, December 18th, at 11h00.
Attendance was open. The expectation is that invited classes at ISCTE might start a local community of technical writers, possibly under the sponsorship of the new chapter EuroSIGDOC.
I took the opportunity to add two slides and create the definitive version of the presentation.
Although initially I didn't think twice about it when Carlos Costa invited me to give the talk, I felt truly honored to tell my wiki story to his graduate students, which replied with interesting questions and observations.
A small software company with a worldwide presence uses one wiki to store or access most company information. Using open source software, the wiki started as a small team tool and then grew to reach technical people. An innovative content strategy proposal later extended the reach of the wiki to non-technical people. Five years later, the system is still the backbone of the company.
Crucial factors for the unusual adoption of the wiki included technical competence, judicious leadership, champions at the executive committee, and a compelling proof-of-concept.
Design of communication at Altitude Software
This presentation covers the adoption of wiki at Altitude Software, including how and why:
- Starting in 2002 as an auxiliary tool for technical writers.
- Growing in 2004 to support the needs of 200 technical persons.
- Adopted in 2005 to become a company-wide intranet that currently serves 500 persons.
Background -- Altitude Software
Altitude Software sells a software product for contact centers, with optional consulting services to set up and customize the solution. The company is based in Lisbon. In 2004, the company had 150 employees in Lisbon including all the R&D staff, and another 150 employees in offices world-wide, mostly doing local sales, consulting, and support.
The product is called Altitude uCI (from unified customer interaction) and is a technically complex software suite that:
- Has a client/server architecture, with several components running in Windows, IBM AIX, or Linux.
- Integrates with third-party telephony switches, databases, and major ERP suites (such as SAP, Salesforce, and Siebel).
- Custom integrations and customized agent desktops can be developed in C, C#, Visual Basic, Java, and even a proprietary programming language.
Phase 1 -- Mid 2002 -- Pool
In the beginning of 2002, the documentation team started to publish internal technical notes with interesting information that, for legal or political reasons, could not be included in the official documentation. For example, configurations and limitations of third-party products.
The custom-built XML toolchain used to publish the official documentation, however, was especially inefficient in handling the technical notes. The team started to look for faster alternatives.
I stumbled upon wikis in the middle of 2002. I read articles on wiki philosophy and wiki usage patterns, and then I used a simple wiki (a Windows application) to take personal notes for a couple of months.
My personal experience with wikis provided the base to choose the software TWiki and set up a team wiki named "Pool" on surplus and obsolete hardware. The team wiki hosted the technical notes and some team pages, and was mostly used by the team for 1.5 years.
Why did I choose TWiki? I liked that TWiki focused on intranet needs, and stored pages as plain text files instead of a database back-end.
Phase 2 -- 2004 -- Technet
At the beginning of 2004, the services department found itself in a situation where the company had lost knowledge of how to do a specific task.
The service consultants used a mailing list to exchange information and ask for help from colleagues. In that mailing list, there was a memory of one consultant asking for help in that specific task, with another consultant offering to share some relevant files. However, the files were sent privately between both consultants, and both consultants had already left the company.
The vice-president of professional services was proposing to replace the mailing list with a Web forum such as phpBB. I argued that wiki was better, because consultants could edit and refine answers instead of searching through endless email exchanges.
I created Technet as follows:
- I hacked the TWiki Comment plug-in to approach a forum experience.
- I transferred the content from Pool to the new wiki.
- I added a plain HTTP server to make available the product documents.
- I configured TWiki shortcuts to specialized systems such as the company bug-tracking system.
The Technet experience in 2004
The slide shows parts of the Technet experience in 2004. The left windows (wiki areas) excel at capturing notes and consensus, while the right windows streamline the publication of curated documents. Integration of the HTTP server with the company directory enabled seamless access both in the Lisbon office and worldwide.
The left windows are wiki areas, editable by any employee. However, TWiki remembers the history of each page and who wrote what, which ensured that edits were made with due care. The top window has technical notes, while the bottom window is an area configured to resemble a Web forum.
The right windows show the combination of Samba with the HTTP server as a way to publish formal documents. Approved users place files in the Samba share, which the HTTP server makes available to all employees. The windows show the official documentation for several product releases, available as read-only documents and HTML pages.
The Technet experience, redux
The Technet experience included four wiki areas:
- Forum -- Area for technical questions based on the Comment plug-in.
- Notes -- Technical notes that originated the first wiki.
- Docteam -- Area to manage the documentation team, also serving as inspiration to other teams.
- Informal -- An area open to employees to encourage individual experimentation.
Technet also facilitated the publication of traditional documents:
- The product documentation was provided behind a plain HTTP server.
- Windows file sharing made publishing documents as HTTP as simple as moving files around.
Technet also explores the following TWiki features:
- Files attached to wiki pages, which provide context for the attachment.
- Wiki shortcuts (such as Bug:1234) to specialized internal systems like bug-tracking.
- A daily email announcing what pages had been changes, sent around noon.
- An authentication system integrated with the existing password system (using LDAP and NTLM).
Phase 3 -- 2004 -- Dissemination
Technet was launched with a series of seminars in Lisbon, plus webinars for offices outside Portugal. Soon afterwards, teams started to ask for their own wiki areas, sometimes private. I was surprised by the instant buy-in from most technical teams.
An unexpected development happened in the executive team, which started to use a private wiki area to manage its meeting minutes. The wiki area instantly solved the eternal difficulty of tracking down the "final version" of meeting minutes among multiple versions exchanged through email, and thus created three Wiki champions: the Vice-Presidents of Marketing, Professional Services, and Research and Development.
After this dissemination phase:
- Most technical documents could now be found on Technet, instead of shared folders and email threads.
- Technet was used by consultants, developers, quality assurance, and the executive team.
Phase 4 -- Mid 2004 -- InfoSpaces
An internal 2002 survey had uncovered the need for a unified distribution of information and documents. A three-person task force from Documentation, Training, and Marketing interviewed department heads and the main information producers. The result was a matrix of producers and consumers of each kind of information.
Marketing coined the term "InfoSpace" for an area of information where producers place information for their consumers. These InfoSpaces came in several flavors:
- Collaborative wiki areas, where consumers are also the producers of information.
- Distribution areas, where a few producers distribute information to many consumers, using file shares or wiki areas.
- Specialized areas, such as bug tracking systems.
I proposed to organize the information flow of Altitude with a specific set of InfoSpaces, featuring:
- Unified logins for employees and partners. The previous standard was for each system to use its own passwords, and for people outside Lisbon to have limited access to resources.
- Nominated editors for each InfoSpace, serving either as wiki gardeners or as content curators.
Even when information is distributed as Word documents, the wiki serves as aggregator, with wiki pages explaining processes to create or use the documents, remembering meta-information such as change logs, and linking to the documents themselves.
InfoSpaces and distribution mid-2004
The slide was presented to Altitude management mid-2004 and summarizes the proposed changes. Columns represent different people, while rows represent different information.
- Employees in Lisbon get HTTP access to all company information, with automatic authentication based on Windows NTLM.
- Employees outside Lisbon get HTTPS access to all company information, with a unified login. For people with slow Internet connections, HTTPS had a huge performance advantage over Windows file sharing over a VPN.
- Customers and consultants get access to documentation, training materials, and product binaries through the Remedy system.
- Sales partners get access to documentation, training materials, and sales materials through the Solutions system.
- Specialized systems maintain their own authentication.
Phase 5 -- End 2004 -- IT takes over
As Technet was growing to become a critical resource to the company through 2014, it eventually dawned on the company that Technet was still being run as a side project on surplus hardware, literally under my desk. The IT department was therefore instructed to take over administration and to provide proper hosting and backups.
Technet became a part of the official company systems and was automatically configured for new employees, but I had to let go of my previous control over configurations and integrations. The change of control had two negative consequences:
- Experiences with deep integrations of TWiki with custom CGIs were lost.
- Some development teams refused to share their information in a system not under direct control of R&D.
Phase 6 -- 2005 -- Marketing takes over
As Technet proved its worth by streamlining the exchange of technical information, Marketing saw the possibility to solve similar problems in the exchange of marketing and sales information.
Marketing led a project to expand Technet to accommodate less technical users, by:
- Designing a graphical home page.
- Revamping the navigation between InfoSpaces.
- Renaming Technet to Altinet.
- Championing other departments to move their information to the wiki.
Thus Altinet was borne, expanding the technical information in Technet with information from Marketing, Customer Assistance, Product Planning, Training, Customer projects, Human Resources, and Information Technology.
However, the process also originated two side wikies:
- Two development teams set up a separate TWiki instance under the control of R&D, for fear that other parts of the company would be able to snoop into their secrets.
- To ensure a higher level of privacy and security, the executive team information was moved to another separate TWiki instance.
Altinet homepage in 2010
The slide shows the Altinet homepage in 2010, essentially following the same design of 2005.
2010 -- Aftermath
In 2010, most company information is on Altinet, or directly accessible from there.
Not all InfoSpaces proposed in 2004 appeared immediately, either for technical or political reasons, but most proposed InfoSpaces appeared in due time. For example:
- Some InfoSpaces required more disk space than was practical in 2004, but became feasible over time.
- Salespeople refused to share customer details until a revised sales commission policy prevented regions from stealing customers to each other.
The process-oriented navigation of Altinet alienates developers, who find it hard to find information, but satisfies sales people.
Finally, Gartner was impressed by the fact that Altitude grew a company-wide wiki, while most companies had separate wikis for teams or departments.
Guidelines for the next travelers
Growing a company-wide Intranet on top of a wiki was a long process full of surprises. Here are some guidelines for people on a similar journey:
- Know the wiki philosophy, so you can advise others on ways to manage information in the wiki. Explain how to do something, or explain why not to do something in a certain way.
- Design both the content and how people interact with the content. Explain to others how work might be better.
- Have champions. Involve users in the adoption process, and reinforce successful collaborations.
- Let go of control over time, allowing others to embrace and extend the original vision.
Thanks for your time.
- 15 slides used in the presentation, as PDF.
Photo by Paulo Ribeiro