Browse Tag by documentation
The blog replaces many internal emails
View Post

Knowledge management and handbooks in the financial sector: A wiki with blog for the Saalfeld-Rudolstadt district savings bank

“Finally, more time for business thanks to the Web 2.0 – The Saalfeld district savings bank cracks open its knowledge silos and finds a new way to deal with rules” by Christian Sauer (summary of the progress report by Nathalie Köpff).

It is well-known that many things in Germany are over-regulated. Instead of supporting creativity and entrepreneurial thinking and action, too much regulation blocks the big picture and leads to redundancy, or in extreme cases to contradiction. The introduction of the Web 2.0 breaks open knowledge silos, helps colleagues share newly-acquired knowledge, in a central place accessible by all, for example in the intranet. Members of staff should have an information platform available which motivates their active cooperation, adding discernible value.

Online organisation handbook and open documentation

The Saalfeld-Rudolstadt district savings bank wiki meets both requirements. One part of the wiki satisfies the statutory and supervisory editorial requirements. This area fixes the procedural rules for business operations. Amongst other things, there is an open area in which the staff can freely document their knowledge. A blog provides support for the system, giving a non-binding form of transmitting information.

The main page of S-Pedia links to important innovations
The main page of S-Pedia links to important innovations

The backing of the management was indispensable to guarantee a wide enough basis for support and initiative. Furthermore, users were needed who really see the need, and last but not least a suitable provider. To get the project of the ground, one has to concentrate on the users, as they will be working with the system later on. For this reason, members of staff from the most diverse divisions of the company were integrated into the planning process right from the start. Taking the requirements of the users into account early on, avoids acceptance problems later on and developments missing the users’ requirements. In the case of the district savings bank, the first job was to determine the central activities clearly and specify a name for the platform: S-Pedia.

Together with Hallo Welt! GmbH, the following challenges were tackled

1. What content should appear?
The wiki needs to display the organisational handbook, i.e. the areas: Organisational and operational structure; company structure; human resources organisation; but also the organisation of safety, equipment and tools, and governance arrangements. As a result, there is an area which needs to fulfil stringent editorial requirements, but also an open area which is principally used as a sort of glossary at the moment. Questions are answered such as “what is a cost centre?” and “how do I calculate a interest reference rate?”.

2. How can I fulfil the legal constraints of editing?
The editorial constraints are very stringent, and the wiki solution needed to offer this. We have a solution in the form of a workflow and approval mechanism, which is only active for the organisational handbook. The company organisation can then carry out regular appraisals.

3. How can existing regulations in Office format be integrated in the wiki?
Many documents had been saved in Office formats on different disk drives. These were integrated into the wiki and are now in a central place accessible to the search function. Changes are easier to follow and the documents are heeded more than they were. This motivates the authors of the handbooks to update them and improve them.

4. Display the expertise of colleagues transparently.
A savings bank with 350 members of staff needs to be able to access information about the expertise of those colleagues quickly, so we created user profiles in which the areas of responsibility and interests of the members of staff are made clear. The name, operational unit, telephone number etc. were taken directly from the central data management system.

5. Reduce information overload and assist communication.
In discussion with users it became clear that there was an overload of information coming from non-filterable notices, reference mails and suchlike. For this reason, we integrated a blog ino the wiki; messages are now set up centrally. Users can subscribe to those sections which interest them or which are in their scope of competence. However, there are obligatory sections, such as “Information from the board of directors”. The blog developed quickly, becoming a lively communication platform with productive commentary and valuable entries in all areas of the bank in just a few days.

The blog replaces many internal emails
The blog replaces many internal emails

Lessons Learned

  • Open source software has saved us costs. This is because instead of investing money in a vendor lock-in, we have used it as part of the handling costs of useful consultancy and customisation services.
  • An experienced and competent provider is extremely important to set up the wiki so it is user friendly and meets our editorial demands, and to choose the suitable extensions.
  • In particular, the part of the wiki which needs to meet the editorial demand is extremely important. Therefore, a great deal of time needs to be planned for, in order to talk through all the existing in-house processes with the provider, so that they can build them into the wiki compatibly.
  • When importing the existing organisational handbook into the wiki, many documents could be discarded because they were obsolete or redundant.
  • What is difficult is the development of new templates and standards. Reading and navigation practices need to be harmonised with the possibilities offered by the new system. There was, however, a significant advantage to be had in article numbering as much of this numbering could be dropped, improving the readability.

Conclusion

Information can be found again; it is linked internally so that the knowledge necessary for a situation can be developed on ones own. The linking to relevant document paragraphs saves the reader from browsing through long sections of instructions. In general, communication is now different as questions are readable by all, and are asked and answered only once.

Next Steps

Almost every day brings new ideas on how we can build up the system and use it even better. For example, we want to introduce “homepages” for individual areas, which can be used specifically for marketing them. Area specific or even personal pages are to be used to replace the reference files still existing with an automatically updated version too.

Creating online documentation with BlueSpice for MediaWiki – tips and hints

Documentation with wiki engines isn’t an innovation anymore, you will find a lot if you look out for them. Especially software developers themselves seem to have a pioneering role in that segment. A lot of those documentation platforms take advantage of the collaborative character of a wiki and let the community be involve in the project. Public but also intern documentaries are increasingly appreciating the specific wiki structures to implement e. g. online manuals. BlueSpice MediaWiki offers powerful tools to support editors while working with the wiki to create online documentations. Please note that a lot of those tools are already available in BlueSpice free, others are additional and fee-required.

The main difference between similar proprietary systems and the open source system BlueSpice is the flexibility: You only get what you really need and you also only pay for the functionality you ordered. Furthermore, with BlueSpice there is neither a license fee nor a graduation of prices according to the number of users. The authorship grows without causing any further costs. And another very important fact is, that there is no vendor lock-in, which means your data belongs to you and is still available even if you decide to terminate the contract.

But let´s get back to the aspects concerning the content in documentations, which are normally most important for the argumentation during a planning and decision phase. In the following, we present the most important questions when implementing an online documentation and give some answers:

Public vs. internal documentation?

In the first instance, the question arises if you want to publish and administrate your documentation public or for internal use. This influences some of the arguments. Of course, it depends on the field of application because operation manuals and organization manuals e. g. are per definition intern. But if you are going to create product documentation, it is worth a thought to involve your customers and fans to work with you. Public documentations offer the advantage of a valuable community feedback. And committed fans volunteer to help editing the content which is profitable for quantity and quality of the documentation. But be aware of SPAM issues in public documentations (have a look at our blog post concerning Anti-Spam-Extensions). In public, but also internal documentations, you need defined guidelines to build structures, help to find content and tools to keep an overview.

Sometimes in internal documentations other aspects are more important than in public ones. For example, many companies have the need for a LDAP/AD connection, so that users can login via single sign-on and don’t have to look for passwords and user names. BlueSpice offers this service with the package Comfort sign-on.

Also important for internal wikis is the possibility to connect different systems to harmonize their functionalities. For example BlueSpice can be connected with SharePoint or DIAS. If you considered your application purpose carefully, you can combine the benefits of the different systems and experience the advantages of a wiki connected to a document management system.

Ask yourself where your documentation platform should be hosted. Most providers offer different solutions and sometimes also a cloud hosting. BlueSpice, for example, also offers cloud and hosting.

Structures in a manual

A manual requires very hierarchical and rigid structures. Due to this, a table of content is of great importance for readers to find their way through the flood of information. If you want to show the structure of a manual also in your wiki you can use the package BlueSpice Bookmaker. With this package you are able to combine single entries from your wiki to a collection of articles. So you can create “books” and even export them. Every article of one book shows a table of content in the content area of the book it belongs to. Navigate with this clickable table of content from one article to the next or jump from one chapter to another.

Page with chapter navigation
Page with chapter navigation

Use portals to summarize topics and collect the most important wiki articles of a handbook. With portals, you can lead the readers to subtopics or provide a general overview. That is how you can divide an extensive handbook into parts and highlight single pages.

In addition to the separation of articles in terms of content, there is a technical way, too. In MediaWiki and BlueSpice it’s possible to define areas which are called “namespaces”. A prefix shows that an article belongs to a certain namespace e.g. “QM:Documentation requirements”. In This example “QM” means “quality management” and shows that the article “documentation requirements” belongs to the topic of quality management. Namespaces separate the wiki into areas and are used to establish the basis for an authorization and permission structure. At the same time search results can specifically be restricted.

To create consistency and structures in the content itself you can use templates. A well thought template contributes to a comprehensive article and the reader is able to get an overview.

Permission management – who is permitted to do what?

Create user groups and define their rights. These permissions are valid for the whole wiki or you can define them just for single namespaces. So if there is sensitive content you need to protect, or you want to create space for the development department, with help of the rights management you can assure that only defined user groups are able to read, edit, delete or approve in this area.

By the way, in MediaWiki and BlueSpice every important functionality refers to a special right, so you are able to define exactly what user group is assigned with which rights.

Set permissions for groups, users and namespaces
Set permissions for groups, users and namespaces

Creating high quality content – what does it need?

Quality in documentations, handbooks and normal wiki articles is opening up a wide field. This is why we start a special series of articles on this issue in our blog. But let´s start with authors of a manual. Mostly there is just a small number of users creating most of the content. These users are very thankful if they don’t have to use the wiki code to format the content. And that is why an extended visual editor (WYSIWYG) is indispensable.

WYSIWYG editor in BlueSpice for MediaWiki
WYSIWYG editor in BlueSpice MediaWiki

At the latest when you start working with tables. If you have to work with complex tables in the wikicode they may drive you crazy. BlueSpice offers a visual editor, which is already included in the free version. This WYSIWYG editor is based on the very popular Tiny MCE. Besides usual formatting functionalities, you are able to create and format tables. It is also possible to copy and paste simple Excel tables in the editor.

Images and screenshots are an essential component of documentation. Therefore, uploading and inserting should be very easy. This is why BlueSpice, compared to MediaWiki, offers a special dialogue for uploading and inserting images. In the same dialogue you can not only define details like licenses and sources but also alignment, size and links. You don’t have to switch pages and edit the wikicode like in MediaWiki.

If you even want more comfort, you should have a look at the package BlueSpice Paste Image. This package enables you to copy and paste or drag and drop images directly from the explorer (also screenshots, which has been created with the “Print” functionality on your keyboard). This saves time and not only wiki beginners will be very thankful when they are able to edit and design an article much easier and faster.

Drag and drop images into a wiki page
Drag and drop images into a wiki page

Sometimes it is necessary or desired that articles are part of an approval process. You can support editing in teams with workflows. Assigning tasks at a certain date to one or more authors helps to assure structured and collaborative editing. If there exist standard workflows you can save and re-use them. In cases of absence or vacation it is also possible to delegate tasks or approvals to a colleague. At a special page you will get an overview of the status of all existing workflows. In BlueSpice you can furthermore assign a responsible editor, who is responsible for a final control and approval of content and images. The status “accepted”, in turn, generates commitment. Only the status “accepted” marks a version as obligatory which means for example only accepted articles can be exported as PDF. Despite this fact it is still possible for authors to edit a “new” draft and actualize contents. To get the full functionality you need BlueSpice Teamwork.

Organize reviews in a team
Organize reviews in a team

Communication and evaluating quality

To assess quality but also actuality of an article at a first glance readers can have a look at the state bar in a BlueSpice wiki. Here they can see the latest author and the date of recent editing. This gives a hint to the editing as well as to the actuality of the content.

Increasing the quality is one of the main goals of the wiki, especially in documentations. Rating and discussing content by readers can contribute to improve quality over the time. So you will find a commenting functionality on every content page. MediaWiki provides discussion pages, which means that every article has its own discussion page where people can exchange their thoughts and ideas according to the content. Additionally in BlueSpice there is a Shoutbox available where you can post comments, useful hints or feedback. The comment box provides the advantage of a lower entry barrier, because it makes it easier to take part at the discussion than a “real” edit.

To evaluate an article as helpful or qualitatively high, you can use ratings (in BlueSpice Rated Comments). Similar to the well-known Amazon ratings you can award an article with up to five stars. Readers are able to assess the quality of an article at a glance. It is also possible to write a detailed recension or, it depends on the use case, experiences, best practices or feedback. These “comments” can also be marked as helpful. This gives you the possibility to get comprehensive feedback – for example in helpdesk descriptions – and already existing but also new ideas can be rated and developed. And if you love gamification you might think of award the 10 best rated articles or something like that.

Special page with all rated articles
Special page with all rated articles

In manuals and documentations media elements are rare. However videos and screencasts are very often a quite useful method to explain difficult procedures in a simple way. MediaWiki (and BlueSpice) offers various players to embed and play videos that are either uploaded to the wiki or hosted at youtube. A range of good “tutorials” increases the quality of contents.

To encourage communication there are not only discussion pages and comments but also an integrated Blog. Use this BlueSpice blog to post news and let them be discussed by readers. If you link the blog at the front page, there is a much higher awareness and people will see activity and progress in the wiki. It is also possible to start single blogs for different namespaces. Just think of the idea to run a blog for every handbook – authors that are involved can coordinate their actions and keep readers up-to-date. Which parts have been edited, which will be edited, where do they need help and also use it to collect suggestions. Let it grow to a central point of interaction about documentation.

But why should we communicate in a wiki when there is telephone, email and coffee breaks? If you start asking questions in the wiki, discuss issues and document answers, the wiki will become a central point of knowledge. All versions and protocols are open to every employee and they don’t have to switch the medium. Nothing gets lost, everyone knows where to look for answers – this is the vision. Additionally, as a back coupling, when people know where to look for information, more users will be an active part of the wiki which means at least frequency will grow.

Who is using a handbook and why? – Search functionalities in MediaWiki and BlueSpice

Let’s start with a short look at people who are using manuals. Nobody reads a handbook from the beginning to the end. In fact they search and read “on the job” – they just look for information they actually need. And normally they need answers on very specific questions. This is why people seldom rummage, because they are looking for a concrete instruction, number or directive. But how do you find this one sentence you need in a mess of information?

BlueSpice offers different solutions. Some of them are already part of MediaWiki, others are extensions of BlueSpice.

If you already know in which environment you have to look for finding your answers, you will be happy about a well structured navigation. On the left side you can link the most important handbooks. Furthermore, BlueSpice offers an individual focus navigation, which means you can add your personal navigation. Fill it with links, pages, categories or tools you need very often. The focus navigation will be your list of favourites. But also portal pages and chapter navigations, which can be created with BlueSpice [bookmaker], offer a good first step into content for people, who already know where to search.

If you haven’t found what you are looking for, use one of MediaWiki’s classics: “All pages”. All articles are listed alphabetically here. You can also filter this list for special namespaces. If you use “all pages” you might have to search meticulously for a title or its synonym – but often you will find even hidden articles.

Another MediaWiki classic is categories. Like tags, they function as keywords for an article and show how to classify an article. With categories you can also get a cross section of the wiki and its namespaces. On another special page all articles that are assigned to a category, will be listed. For example you could get a list of all articles that are assigned to the category “maintenance”. Watch out at these articles for the special issue you are looking for.

Prerequisite for that kind of searching is, that a diligent employee assigned pages, images and files precisely to one or even more categories.

BlueSpice offers two more features to search for content. One is a wiki search that is able to search with query operators in full text and titles and also file attachments and image file names. While you are typing the search term, the system already proposes results. If there is no result you are looking for, you can use an extended search with facets. Use one or more facets like author, category, file or namespace to limit the search results. For example, you can look for articles from a certain author, if you know who edited the article you are looking for. Or you limit the results according to a certain namespace and so on. Step by step you will get closer to what you are looking for. A preview of the articles with the highlighted search keyword in it will help you to decide what result may fit best. By the way this faceted search and the auto-complete function is already integrated in the free version of BlueSpice.

The Wiki Explorer is a fee-required package. With its functionality you will get an interactive table where all articles are listed alphabetically. Choose different columns to define the criteria you are looking for. In the columns you can define filters for every criteria. For example in the column “size” you can limit the list to articles with more than 750kb. Which means only articles that refer to this criteria will be shown in the list. By the way [wiki explorer] is often used by wiki gardeners to find out which pages still have to be approved. You can filter the list of articles precisely by using several columns and define the criteria.

Filter content with wiki explorer
Filter content with wiki explorer

There is another case, in which people are looking for a detailed report of what has changed in between two versions of an article. What changes have been made in this instruction or directive? BlueSpice offers the possibility to compare any two versions of an article with the package Visual Diff. What’s special about this is, that in comparison to MediaWiki, changes will be highlighted in the text and not in a table of wikicode. Added content will be marked green, deleted content red and so on. That makes it easy for you to find even the slightest change in a large article.

Highlightling of changes in an article
Highlightling of changes in an article

Import and export of data and files

When you start with an online documentation you should rethink, if and how existing material shall be integrated. Define how you want to transfer existing numberings and references and take this opportunity to tidy up and throw out old stuff. Data sheets in word, excel and pdf can be uploaded and linked in the wiki but ask yourself if a transferring into a wiki article is more reasonable. This decision depends on the complexity of contents, images and graphs.

Please keep in mind that during this year we will develop a WebDav protocol, so uploaded files can be presented in a folder structure. Furthermore, as we mentioned in the beginning, it is possible to connect file systems like SharePoint and DIAS.

But let’s get to the export. Handbooks or parts of it are often needed on site as PDF or Word. With Bookmaker you can export single pages or whole books as PDF with a cover in your individual design, a clickable table of content, attached files and prodding to approvals (reviews). It is also possible to export to word or html to reuse content in other systems like a DMS or web-based systems like Typo3.

 

It can be summarized that BlueSpice is, like other wiki engines, well suitable for documentations and handbooks. BlueSpice’s benefit is it’s Open Source core, which means you will get a software without licenses, no vendor-lock-in and you can choose and add only those packages you really need. In addition to this, we develop individual extensions. And on the other hand BlueSpice offers, like proprietary vendors, solutions that include everything you need to fulfill all the conditions for certain use cases like documentations.

Have a look at the BlueSpice homepage to discover more. And if you think about realizing your documentation or handbooks with a wiki, please contact us. Hallo Welt! Is a very experienced partner and we will be happy to support you.

 

The home page of transpedia
View Post

Create technical handbooks in an enterprise wiki – the TenneT TSO example

tennet-logo-180pxManaging documentation and handbooks has become one of the most common uses for wikis in companies. But how does such a platform actually look? Well, let us show you the business wiki “transpedia” from TenneT TSO GmbH.

TenneT TSO GmbH is a German subsidiary of the Dutch electricity supplier TenneT operating an ultra high voltage network (220kV and 380kV) with a total length of about 10,700 kilometres. This gives them coverage of 40 percent (140,000km²) of Germany so they indirectly supply about 20 million people with electricity. TenneT constructs and operates infrastructure for transmitting electrical energy both on land and at sea. In order to construct and maintain these far-reaching networks, they need to put guidelines in place. TenneT has been using a Hallo Welt! wiki since 2009, to maintain their technical regulations and keep them up to date. The system was upgraded to the newest BlueSpice version in 2014.

Essentially, it involves the handbooks Building and Construction (BuE), and Network Management and Working in the Network (NAN). These contain the internal regulations concerning the construction and operation of the technical equipment and, since 2010, have been displayed in “transpedia”.

Why was the decision made to manage the handbooks with a wiki?

Business was partitioned into two divisions: high voltage networks and ultra high voltage networks. This made it necessary to reorganise the online handbooks available on the internet at that time. This means that some thematic blocks were no longer needed, and other information needed to be reworked and made available in a similar way to what had existed before. The wiki was used to update the technical regulations as quickly as possible without engaging external services or initiating complex working processes. The approval of changes and additions was decentralised, being assigned to those responsible for the area. The wiki also offered the chance to improve knowledge management in general with the addition of a glossary.

What subjects does the wiki deal with?

The wiki has two main focuses: firstly it contains the technical regulations, and secondly it serves as a company-wide reference work.

The operating manuals contain instructions on how to handle the technical equipment, software etc.. The handbooks provide important information about servicing, construction, renewing, network management, working in the network, occupational health and safety and environmental protection. These technical regulations are regularly updated by the staff and the approved versions are binding.

The wiki’s glossary serves as a central registry and encyclopaedia. The contents which belong there can be found in the main namespace. The information in these articles is non-binding.

The home page of transpedia
The home page of transpedia

How can they be sure of quality and how is it made clear which content is binding?

The rights structure has been kept flat so that the wiki is equally open to all. There is, however, a difference between authors and editors. The editors have the right to approve handbook articles, after reviewing them. This makes this version of the article binding. This approval process ensures the validity of the data. To allow the article to be continually worked on, every user has, however, the possibility to continue to edit the article as what is known as a “draft”. However, the last approved version is shown in the read-mode. The reader can see the approval status directly in the article. This means that checks can be done “on the fly”, without having to initiate complex processes. To verify the article, it only remains to turn to the relevant committees or supervisor. Along with this, articles in the handbook have a responsible editor, so there is an obvious point of contact. Editors get, for example, their authority for approval in this way.

Everyday work in Transpedia

Internal users are logged on using LDAP / single sign on, which is currently used by many systems to save time searching for passwords. Authors are helped by being able to use page templates when creating articles. These point to individual subareas in the handbook and to the assignment of namespaces and categories.

There is a hierarchical navigation system by chapter in the handbooks. This enables the contents to be structured in the same way as in other systems but also speeds up the finding of specific information. This gives the wiki the handbook feel, promoting the acceptance of the system and supporting well-known search strategies.

The display of necessary mathematical formulae is realised by an interface with the typesetting program LaTeX. There is also a connection to a document management system (DMS). This is because the most up to date versions of the technical drawings are saved in this system. The wiki pulls the most up to date version from the DMS every night, and the corresponding contents in the wiki are kept up to date with this synchronisation. The editor is informed and can approve this version for the wiki. After being approved, this version is then part of the contents of the handbook.

During the last upgrade, MySites from Sharepoint was connected to the wiki, so readers are able to see more about the authors of a wiki article, without the need to duplicate information.

Exporting from handbooks

Many members of staff and external workers need parts of the handbook as a PDF over and over again. The sections can be collected according to need and exported. The sections are chosen, and the choice is exported as a PDF brochure including attachments, notes and approval.

Conclusion and lessons learned

As far as every-day work is concerned, the transpedia users are often tripped up by creating and formatting texts because up until now they have usually used Word for such purposes. A visual editor is, however, browser based, and one needs to be aware of the fact that a WYSIWYG editor is not Word. It is therefore advisable to manage expectations to that effect.

Instead of parallel, cyclic changes there are dynamic changes which are also documented. Due to the responsibility of various technical editors, it is quicker to get approval, saving everyone time. Assigning of editors to articles and the necessity for approval of changes was easy to communicate, however the separate approval of files was often overlooked.

Editing of the articles and establishing the system at TenneT needs system maintenance. This challenge must be further channelled (when, how, who), particularly for articles and files, which is particularly apparent when there is staff change over. The plethora of articles has been growing for four years, this and the greater necessity for keeping the articles and handbooks up to date requires ever increasing maintenance work.

The system construction needed almost one and a half years at the start which meant comprehensive development work for TenneT. The upgrade, which contained further customisation and extension of the system, took another half year.

That is really nice is that we can adapt the system – you don’t have to just take it as it is. In particular, small adaptations are done quickly and reliably by Hallo Welt!. The cooperation is uncomplicated, smooth and hitch free.”
(Michael Nawratil, Asset Management, TenneT TSO GmbH)