Help:Maintenance

Do you want to get into documentation maintenance because you've read it's the best way into an open project? Do you believe that this wiki can be improved? (We do, too.) Help:Maintenance explains to the willing contributor what can be done and how.

Note: this article expects you to be already capable of generally adding contents to a wiki. If you're not sure, please check that at Help:Your first article.

To who's not happy with this wiki

You probably approached this corner of the wiki after consulting it for a while and not finding it suiting your needs. Maybe with some frustration too. And some revolutionary plans. We've all been there.

There's something you need to know: the organization of this wiki has been already discussed a lot, and "a lot" here means since its early years, and will also be in the future. The critiques go from the mild suggestions to the tearing to shreds, and even non-constructive comments (ahem) were given. This is in all likelihood due to the bazaar nature of the FlightGear project. What is actually needed, though, is lacking: time spent doing something, instead of discussing it. This is because the number of regular maintainers/contributors is way, way smaller than you think. To verify that, skim through Special:RecentChanges and count the most common usernames. So, before suggesting something, you'd better be ready to realize that.

But cheer up: despite the above, this wiki gets every day better and better. Ask a maintainer if you don't believe it!

This document was originally written by someone like you, who thought it could save you some time to get to full speed (like the time you'd use to write your detailed, well thought and argumented plan - too late?).

Working your way up

To become a full grown maintainer it is fundamental to get acquainted with how the FlightGear project works. It's probably less obvious to do than it seems, it'll take time and time spent living the community. Some articles you may want to review are:

• Volunteer
• How the FlightGear project works
• Forum communication
• Howto:Understand the FlightGear development process
• Howto:Start core development

While reading those documents, it's a good idea getting in the mood of checking if anything can be changed, fixed, made clearer. Doing some random maintenance while exploring the wiki will help in gaining confidence with both the project and how the wiki is organized. Mistakes are around the corners, but maintainers will keep an (hopeful) eye on you, so don't be too shy and, if in doubt, better to ask than to forget.

The summary

But please, always remember to add a meaningful comment to your edit. It is the "Summary" textfield you can see below the editor textbox. Your common sense should be enough to make up an appropriate description of what you're doing, but if you need examples the Special:RecentChanges page is a copious source of them.

This message is not just a reference for the future - actually, most of them won't be read anymore - as much as a message to let other maintainers know what you're doing now.

Recent Changes and Watchlist

Special:RecentChanges is the primary maintenance tool of the FlightGear wiki. It is messy at first sight and will require a couple hours of work to get used to it, so it's better to start early. There you can see what's going on, who has been working lately and what was done.

It's a lot of condensed data, and at first you might want to concentrate only on few articles that you're following. You can do that by putting them into your Special:Watchlist, by clicking the star at the top right of their pages, next to the search textfield. Not only any edit on such articles will appear in that list, but it will appear in bold in RecentChanges.

However, it's unlikely that you're following a very busy article. Those tend to be quite messy and usually regard development stuff that, we'll see later, have their own rules. So you might just "star" your own talk page, to be sure not to lose any message directed to you. Oh, and the Village pump!

More on tracking changes at mw:Help:Tracking changes.

Category Tree

Another valuable tool, that you might already know if you were a good contributor, is Special:CategoryTree. It provides you with an overview of the categories and their organization. This is possibly the most discussed aspect of the wiki, so you might feel the urge of just changing everything as if that was your /home dir. Chill down, you can't do that: a) it's technically almost impossible; b) it needs to be discussed with the more experienced maintainers.

However, you can still take a look. You'll see that the FlightGear wiki has a root category, called, with no much surprise, Category:FlightGear wiki. You can tell that by looking at Special:UncategorizedCategories, which lists categories that have no parent. So use the CategoryTree tool on that (you may ignore the namespace option for now) and take some time to see how it's structured.

In general there should be an Articles category, where all the text content is available, and Files, where the binaries are (probably just images). The other are technical categories, for which the use should be self-explanatory.

Communication with other maintainers

Talking about discussing with the other maintainers, let's spend some words on that. Communicating through the wiki requires some adaptation. It is cumbersome at first, still annoying having to care about the indentation and remembering to sign your comments, but you'll get used in a couple days.

One thing you should be aware of, though, is that you won't be warned of replies to your messages. As a surrogate to that, you can "star" the page where you left your message, but you'd have to remember to "unstar" them, or your watchlist will soon become unmaintainable (if that's a problem). As a maintainer though, you'll probably leave around so many messages that it will be easier to just check the RecentChanges as you should already be doing.

More on communicating at mw:Help:Talk pages.

About discussions in this wiki

Sometimes you'll want to know the opinion of others on what you're going to do. It is possible that you won't get answers, which could mean two things:

• if you need the help of others, evidently you should try again at another time;
• if it's something you can do by yourself, then you should go on in most cases.

In the latter case, in fact, the absence of response can be read as "Ok, I don't mind if you do that, in case, we'll discuss the results". Obviously, that's true if you gave everyone the chance to review your question. This convention helps in keeping the effort of discussion to a minimum.

To make it short: instead of asking the permission, announce what you're going to do.

Ordinary maintenance tasks

With only few hours of the above, you should be up and running. Here's briefly explained what you can already do. Note that you're by no means asked to do all the following, any help will be appreciated.

Checking new articles and edits

Checking Recent Changes you might find an entry marked with an N, meaning that a new article has been created. Go and see if it fits the wiki (e.g. doesn't talk about the user's dog), if the title could be made clearer, or formatting could be improved... in brief, check its quality.

Moreover, check if it is categorized in the most specific category available, especially if it is not categorized at all! This one, though, might be a task that needs a bit more of expertise, particularly for development related articles.

If the new article was made by a new contributor, you might want to leave some hints on his/her talk page to avoid the repetition of any mistake (like forgetting the summary). Needless to say, remember to be nice: that contributor probably did the best he/she could. In fact, you might also consider just thanking them for their addition.

If you change anything, remember to leave a proper summary.

Checking user entry points

Due to its high impact on the wiki quality perception, this is possibly the most important maintenance task available.

You might have heard of the Pareto principle. Briefly, it says that 80% of the results are due to 20% of the causes. Applied to the wiki, it could sound like "20% of the wiki pages affect 80% of the wiki quality perception" (numbers may vary).

These pages are of course the most visited ones, that is, the Category:Portals and all the pages linked there. Try to use them as a user, see if some topics are missing or if it is out of date. If the topic is suitable for you, try to fix that even by searching and asking on the forum about latest updates.

Another page that needs to stay up to date is Frequently asked questions. Try to remove, or at least signal with a template, questions that you presume asked no more that frequently. Also, by following the forum you should be able to know what really are the FAQs, so consider adding them if missing. In the answers, try to point to existing articles instead of duplicating information (see below).

Then, if you're out of "most visited pages", just check Special:PopularPages, which has (at the time of writing) about 1,900 of them.

In FlightGear terms, helping maintain such articles has a great multiplier effect because end-users can more easily use the software and get better support. Likewise, there are articles that are basically entry points for aspiring contributors wanting to do for example scenery/aircraft development or helping with the forum/wiki/newsletter etc, those also have a significant multiplier effect, because the project is gaining more momentum and traction through additional contributors.

This is also why certain pages are more "important" than others, because providing high-quality support is usually difficult and requires certain background knowledge, i.e. can often only be provided by people involved in the design of a certain system or feature - thus, providing good troubleshooting guides that enable people to make good bug reports is extremely helpful to reduce the degree of manpower necessary to deal with certain enquiries.

Maintenance reports

Although when seeing a problem it's better to fix it immediately, you might really not have the time/will/knowledge for that. When this happens, you should however add a maintenance template. These are those message boxes that appear on top of articles or sections that need some attention. The articles that contain them are listed in some subcategories of Category:Wiki maintenance. The ones you'll most be interested in are:

• Category:Cleanup - these are also good candidates for the quality checks we talked about earlier.
• Category:Articles to be expanded - like above.
• Category:Considered for deletion - these should have a discussion ongoing, you may give your opinion.

Every now and then, you should really go back to these lists, and see if you can do anything to empty them. Maybe with time you'll even be able to fix a page that you signaled yourself some time before!

More random checking

Sometimes you should just go out in the streets and take a look around, just to be sure everything's fine. A lot of stuff, in fact tend to be forgotten and slowly grow out of date. Some pages you might want to visit are in Special:PopularPages, Maintenance reports you don't usually check, High use pages.

Some guiding principles

Maintenance can become a real chore sometimes. To avoid that, maintainers try to keep their work simple. Here are some hints.

Avoid duplication

Writing something in multiple places means that it has to be kept up to date in multiple places. A good categorization will help in finding similar articles, that should be merged. Also, you should strive to keep different topics separated, which you can do by splitting articles or moving sections to more appropriate places. Templates, to some extent, can help too.

Write for the posterity

What you're writing now should aim at being valid for the longest time possible. So try to keep things as generic as possible, and to link to existing articles that will be updated on their own (this of course also to avoid duplication.)

Keep the quality perception high

A non maintained wiki will keep away both users and contributors. However, their judgement is only based on the perception of the wiki quality. Keep this one up by maintaining entry points, and people will be happier to contribute.

Organization of the categories

FlightGear wiki is the root category. From there, you can easily browse all the categories. Note that existing category pages have a short description at the top, which might need to be maintained as well as other pages, but is intended to be a guide for working with them.

Although in MediaWiki the category hierarchy might seem to be shaped like an actual tree (and could be so), more often it is structured like a web. In fact, every article - and every category - can be in more than one parent. This means that there's often more than one path from the root to an article. This feature can be leveraged to make a certain article better reachable by users that come from different areas. An example is given by 3D modeling related articles, that are useful to both scenery and aircraft developers. In the case of Category:Aircraft, this feature is used to classify by various aspects the planes.

Keeping the tree sane

However, this can also make things messy sometimes. There are for instance cases where you might find loops, and those should be avoided. This is definitely not an easy subject, even choosing the name of a new category is not trivial at all. You might find some guidelines on categorization at [[wikipedia:Wikipedia:Categorization#Category tree organization|]], and a thorough analysis of pros and cons (and alternatives) at Wikipedia:Categories. These things, however, should be handled only when you have a sufficient knowledge of the whole wiki, and after discussing it with other maintainers.

Limitations of MediaWiki

Categorizing like tagging doesn't work

MediaWiki doesn't support (at least natively) the use of categories like tags, that is, the use of two or more unrelated categories that combine to make a particular one. This happens because when browsing the categories you can't combine them. So one should always use the most particular category that is possible, which might not be easy, given the convoluted nature of the category tree that even presents some huge loops.

An example: if an article is about creating airport layouts, it shouldn't be "tagged" with Scenery and Development (they're both into Category:FlightGear), but classified into Scenery enhancement (which is another way of saying "scenery development").

Editing categories is cumbersome

There is no other manual way to edit the category tree (e.g. moving articles, renaming categories...) than editing one by one each categorized page, be it an article or a category page (and thus, the category itself). To some extent, such work can be done by bots (automated software editors), but they're pretty dangerous and their usage must be very carefully planned and tested with maintainers and admins.

Promoting your ideas

You've read this paper, you've done a few days of maintenance and still are convinced that your idea is worth to be discussed, and you're intending to support it. Great! Write about it at the Village Pump! Tell about it to some maintainer! Don't be afraid, it will be discussed. You might even find that it was already proposed, but that nobody ever put it in practice. If you think you were not understood, insist. If in the end you get no support, well, you have tried. That's how the FlightGear project works.

Note  Please keep in mind that some of the best ideas recently implemented in FlightGear, or some of its infrastructure, still had a "shelf life" of 18-24 months - not because people wouldn't recognize good ideas, but simply because there's usually a very narrow "window of opportunity", where resources such as manpower, spare time (holidays), skills, expertise, experience and community support all align such that good ideas can actually be turned into new features without us having to drop something else. This is one of the most important aspects of how the FlightGear project works, and it is one of main show stoppers for newcomers: people expect their feedback to be acted upon immediately - unfortunately, we usually don't have the resources to act immediately, even if you should have an excellent idea. And lengthy discussions, especially heated ones, on the forum or the devel list aren't exactly helping either (no matter how you right you may really be!), because those take up precious time, too. It usually works better to file a feature request that can be reviewed by others, or even create a wiki article (e.g. RFC/RFD) so that others can keep an eye on it, i.e. to build up momentum over time. Sometimes, you may not get any feedback for months, or even none at all - this happens even to the most seasoned contributors, including core developers who've been developed for over a decade - it's not generally a sign that people dislike your idea, but that it would take up too much time to deal with it (keep in mind the Release Plan) at the time being. Thus, timing really is important. As is building up "momentum" (ideas, knowledge, tutorials, articles, support, skilled contributors). Honestly, we've had thousands of remarkably excellent ideas discussed over the years - but the reality is that ideas are worth a dime a dozen: actions count so much more, which is why a mediocre implementation beats an excellent idea. The perfect being the enemy of the good. As contributors, we tend to use the terms hack, workaround or prototype whenever we aren't exactly proud about our "short-term" solutions, which usually still end up being a part of the project for years. Actions speak louder than words... Over time, you'll find that even the most seasoned contributors once were in your situation, and felt exactly like you, even if not even much more frustrated. As long-time contributors we're probably much more aware of FlightGear's ugly corners and issues, but we're trying to use this knowledge to motivate us, and to get involved in some way. There are quite a few areas that used to be unmaintained and underdeveloped for years - some of us have meanwhile become maintainers of those, not because we were asked to do so, but simply because we started contributing there. In other words: embrace the opportunity and be the change you want to see, even if that means filling a void - which may feel frustrating and discouraging at first, but at least you get to come up with your own terms that way.