If a help link points to a non-existent mapping, it goes to a default page. This means that writers can move and rename documentation pages without changing the help links in the product. There is a file that maps the tags and product version on the page to the link from the application screen. Rachel recommends a minimum of three tags to ensure a unique combination. Each page can have any number of tags, and those tags form a kind of unique help ID for the page. This is another wiki customisation, done via tags (labels) on the pages. This means that all contributors know which version to edit. Everyone can see the versions numbers across the top of the page, indicating which version(s) the page applies to. The general public will only see the newest version when you change its status to released. Note from Sarah: This is very neat! Permission control (via MediaWiki’s access groups) is by version. Note that a page may or may not need changing for a particular version. So, for example, if you change the content of an earlier version, you may need to apply the same change to the later versions too, and you would have to do that manually. There is no awareness of the content itself. Splunk have created a tool called the “Branch and Inheritance Console”, where you choose the version you are branching from and to, choose the manual or pages that you want to branch, and then complete a number of selection fields to create the branch. You can branch a page, a set of pages, a manual or the entire documentation suite. You would then branch the page, so that you leave one branch documenting the earlier version of the product and another branch for the new version. What is branching? Let’s assume you need to change a page because the functionality it describes has changed in the latest release. Each version has metadata that defines its status, such as released and unreleased. Similarly, there is a text file to define the versions of the product. If the page does not exist, then the tool creates a new shell page and populates it with template content. If you load that page in view mode, you can click through from the table of contents to each page. Another text file defines the table of contents of each manual. One text file defines the list of manuals shown in the dropdown list at the top of the screen. To create the structure, writers edit a text file. Splunk have added wiki customisations to support the division of documentation into manuals, chapters and pages. PDF versions of the manuals are very popular. This functionality is provided by an open source plugin that Splunk has customised. It only regenerates the PDF file if there has been a change to the content. The way it works is that the tool caches the PDF file and serves it up to each reader. Customers can generate them on the fly, for the entire manual. Rachel monitors all updates via RSS feeds, which are a standard feature of MediaWiki. The advantages are that readers always have the latest information, and writers can fix problems at any time. Rachel estimated that it took about two months for them to get over their apprehension. At first, authors were a little disconcerted that there was no lengthy publication process. The content is immediately available, as soon as you save it. The authors value the “live” aspect of the wiki. It is also important that there is a lively community of developers. Rachel explained that the primary goal in selecting MediaWiki as their platform was to make the documentation as collaborative as possible.
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |