As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 9 years ago.
I need a tool for collecting feedback and new ideas inside our company regarding our internal IS product. The problem is the acceptance level for such a tool.
Most of our colleagues are not IT oriented, so a solution like BugZilla or Jira is way to complicated for them to use. You need to create an account, take care of a lot of parameters before submission, new ideas about new software doesn't really fit well in these tools, etc...
So, here are my requirements:
No login need, or optional.
Few fields to enter.
If possible a WYSIWYG editor for the main description field.
Web based or E-mail based (we use outlook internaly).
Free (as a beer).
Not too chaotic (a Wiki is not an option)
I've take a look at uservoice (of course), it's really a nice tool for experienced people, but too complex for my target users.
Is the feedback you are seeking possible to collect through a questionnaire? There are many free solutions that provide you with questionnaire forms very easy to use, and if none apply it is also something relatively easy to implement.
I also do not understand why a wiki will not be a good solution, but regarding the Outlook, you have the possibility of doing simple votes (approve/reject) (yes/no):
See: http://www.microsoft.com/atwork/worktogether/forms.mspx
If the barrier to actually use the tool should be minimal, then perhaps the best way to collect the feedback is to use an e-mail address. Everybody knows how to use the system, so there is practically no barrier. And the feedback that is provided has to be processed by developers / management anyway, in order to decide what concrete actions are going to be taken. The developers can then use whatever system suits them best in order to keep track of bugs, immediately required functionality, nice-to-have features that can be implemented later, etc.
Some "defect tracking tools" handle this.
Don't vote down because of "defect tracking". Some of the tools are enterprise and handle incidents, requents, requirements, etc. And, you can go to one place for bugs and enhancement requests.
Microsoft's Exchange server has support for Public Folders, email lists/groups. This may be an easy introduction to collaboration for your environment, using tools that are familiar. From the Microsoft Help on Public Folders:
Public folders are an easy and
effective way to collect, organize,
and share information with other
people in your workgroup or
organization. You can use public
folders to share files or post
information on an electronic bulletin
board.
I'm not sure how effective the tools for managing those "lists" are - I'm not sure if you can mark responses such that all users see the mark, for example.
But it is probably a good start. As people start to see the value of collaboration, something along the lines of a Wiki becomes more appealing.
I've got to say that Confluence, especially now that editing with Open Office or Microsoft Office tools is possible really deserves a look. Not free (as in beer).
I would think a locally hosted php-bb (or other...) forum would be a good choice, as you could moderate it and have a FAQ and history that people could check before duplicating suggestions. So, that's the advantage over a simple email address, and it has a simple, known interface.
What's too complex about Uservoice? The main UI is a single question ("I suggest you ..."). Your users can be anonymous, one field to enter, web based, free for small users. Seems to tick all the boxes except the visual editor. Even administering it is not terribly tricky. (I use it for my iPhone app.)
It looks like you're facing a very standard tradeoff - you want your feedback to be structured, but you don't want any impositions upon your users.
You can't have your cake and eat it too. Why is a wiki off the table? Wikis were designed to balance this kind of tradeoff.
You could use Google Documents to create a shared spreadsheet. Your uses will need Google accounts, but they only need to log in once and a cookie will remember them for next time.
Hum, I've found that we've also InfoPath as part of our toolset. I've never use it, but maybe that it could do the job.
How about using for example Google groups? I've found a mailing list works quite well for this kind of purpose.
Edit: or how about http://getsatisfaction.com/
Related
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
I am going to look for a job as a software tester (a SDET maybe), especially for website test. I have some vague impression of this area and got a couple of specific questions as below:
Among so many documents, such as functional spec, design spec, which should I pay more attention to? How to view them in a tester's view?
Any good suggestions about writing test spec?
Any attention should be paid to website test?
These are just some questions I got now, I'll update with more shortly.
I'd like to hear your voice very much. Many thanks.
Credentials: I'm an SDET with 5 years of experience, 2 of those years testing web applications.
1- I'd say testerab has a pretty good answer. There is no single document that you can invariably rely upon across companies or even teams within a single company. Pay attention to whichever document has information.
I'd augment that answer with this advice: Don't be surprised if the documentation is insufficient. Strike up strong relationships with people who help define the product (the dev, the business owner, the program manager, etc.). You will nearly always be relying on them for some of your specifications, since it is difficult to cover everything on paper (and, as you gain expertise as a tester, you will learn to see things that others don't notice). Try to write down any "verbal specs" as you hear them, and ideally get any requests for specification clarification in writing or email. Gathering them all in a public document is wise, and may help to uncover if two people have very different ideas about what the spec "ought" to be.
2- Testerab has a good answer to this question, also, here: How Do You Keep Automated Tests in Synch With Test Plans
"1) Who reads it? 2) Who should probably read it, but currently you suspect they don't bother? (Do you know why they don't bother?) 3) What information do they need to get from it? Does it give them that info? 4) How do you currently present that information? Does that work for your readers/non-readers? 5) What sort of feedback do you need to get from the readers of your test plan? 6) Do you have any regulatory requirements that you need to satisfy with your test planning? "
Test plans, like product specs, will vary greatly depending on the needs of your group. If you are in an Agile group you may spend very little time on your test plan, doing little more than outlining the areas you need to cover - or you might not even have a test plan at all, but just a conversation with the team about what will be sufficient testing for everyone to feel confident about making decisions about the product. Other companies will have very specific guidelines you will need to follow.
Cem Kaner's classic book "Testing Computer Software" is slightly outdated, but still a good place to start and discusses test planning. I'd recommend you buy a copy quite strongly, unless someone can recommend something as authoritative that is more current. Last I heard, this was still the software testing book.
3- I'm having a little trouble understanding this question, but will do my best. Do you mean, what specifically will you need to know to test websites? First, what do you mean by websites? Do you mean web applications? If so, you will probably need to understand server / client architecture, web services, databases and basic SQL, at least rudimentary security testing, integration testing, functional testing, and will benefit from an understanding or specialization in performance testing, load testing, more security testing, and familiarity with web GUI testing with Selenium or Watir.
Some helpful things for us to know to help you get started:
How much experience do you have, both as a developer and as a tester? If you are just getting started in your career, what is your educational background?
How much experience do you have working with web applications, and in what roles (dev, test, PM, etc.)?
And, you might want to try asking some of these questions over at http://www.softwaretestingclub.com - this is a site for software testers to build community. You will get a lot of good advice and support there, so long as you are active in the community, and many of the most influential software test writers hang out there. If you do stop by there, feel free to look me up!
Hope this helps!
Edit: Added some info to answer q. #2 and to mention Cem Kaner's book.
I'm a developer with 2 years .NET experience and 1.5 years previous testing experience and an ISTQB/ISEB Foundation qualification.
To answer your questions:
1: A test manager will (typically) have a test plan and awareness of the specification documents to be tested against. Using what a developer is using is a good start. If the development methodology is agile this will probably be "user story".
A good way to look at the documents is to go through and look at where individual elements of functionality are specified and create steps to exercise them (see some of the functional techniques below).
2: What do you mean by "test spec"?
You will need to prioritise the areas of the application that need testing and understand the coverage needed. A "Test case spec". (or test script) will fit into higher level documents (like Test Plans, and Test Strategies) can be efficiently and effectively written using some Black box (Functional) techniques including:
Equivalence Partitioning,
Boundary Value Analysis,
Decision Tables,
State Transition analysis,
Use Case analysis (which could be based on a user story)
to come up with scripts that contain test cases. These techniques can be looked up online.
White box (Structural) testing involves an awareness of the code and includes:
Statement Coverage,
Decision coverage
If you're are looking at a website, this may involve JavaScript; QUnit is a testing framework for automating JavaScript testing and would be useful to research. NUnit is a commonly used test framework for .NET applications (including web applications) - NUnit was ported from its Java equivanlent JUnit and has been expanded (most probably owing to the popularity of .NET).
3: I don't understand what you mean by this? A web application will need to be tested in many different ways, and contains server and client functionality that will be tested using different techniques and the testing needs will need to be analysed. It will depend on the project.
As mentioned in other answers there are also other types of testing:
Unit - modular testing of functions at the lowest possible levels
Integration - testing functionality between different functional areas
Regression - testing to ensure that previously working functionality hasn't been broken by changes
System testing (Functional) - ensuring that the code/system under test is working as specified
System testing (Non-functional) - ensuring that aspects of the system that may not be specified are appropriate e.g. performance, load, stress, interoperability, maintainability, reliability, portability, usability
Acceptance (something called User Acceptance Testing or UAT) - ensuring that the system under test is fit for use
As mentioned in other answers, you will be retesting existing defects and inclusion of these to your test scripts is a good idea.
Hopefully this answer has given you a lot of food for thought and a good base for research. Testing qualifications or a role as a Junior Tester in an established team to build your understanding and experience could prove to be very useful.
"Among so many documents, such as functional spec, design spec, which should I pay more attention to? How to view them in a tester's view?"
Being able to extract useful information from many different sources of documentation is a critical skill for a tester, so you're right to identify that as an area you need to look at. The documents you need to look at will vary from project to project, and from company to company, so there isn't one good answer about what document you need to look at - but having good specification analysis skills will mean you'll be able to cope with whatever you're given.
For that, I'd strongly recommend this BBST course on specification based testing - it will show you how to analyse specifications, applying the Satisfice Heuristic Test Strategy model. That should also help you with your second question about writing a test spec.
http://www.testingeducation.org/BBST/BBSTSpecificationTesting.html
I'd recommend the BBST courses in general - the course materials are all available freely online, at the website above.
If you're really serious about testing, you should also consider taking the online course from the Association of Software Testing. The Foundations course is free to members, and you'll get the opportunity to practice your skills online, gain really valuable feedback on how you present yourself and your ideas, and you'll also meet a lot of outstanding testers, both as fellow pupils and as instructors. It's hard work - but if you're willing to put the effort in you will really get a tremendous amount out of it. Being able to discuss the basics with other people will really help you to get a deeper understanding.
my 50c
If you don't have test specs, or any kind of specs, you can transform your bug reports into test plan.
For each bug report that occurs, create one test item. That way - you'll have list of tests that you can follow when doing regression testing.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 9 years ago.
Improve this question
I'm responsible of finding a good way to document the software project I'm working on.
What things are important to document? Should documentation of code and design mainly be in the code in the form of comments? Should we put text files or Word documents directly in the source control togetether with code? Should we use a wiki?
Factors to think about include how easy it is for the current team to create the documentation, and how easy it is for other developers to find, correct and extend the documentation later. My experience from many projects is that developers tend to not write documentation because the system for writing it is too complex or developer unfriendly, and that after a few years, new developers can hardly find the little documentation that was written.
I'm interested in what approaches you have used in similar projects. What worked well, what did not work well, and why?
Some key facts about the project:
The platform is C# and .NET.
We use Visual Studio and Team Foundation Server for source control and work item (task) management.
We use Scrum and test-driven development and are inspired by domain-driven design.
The software consists of a collection of web services and two GUI clients.
Other clients are going to integrate with the web services in the future. The integration will be done by other developers on other teams (so the web services form a kind of API).
SharePoint is heavily used throughout the development environment. Most projects have a SharePoint site, including ours.
On our project's SharePoint site we currently have a bunch of MS Office documents on things like requirements, design, presentations for stakeholders etc. Keeping everything up to date is hard.
We also have a SharePoint wiki for the development team only, where we document things in an unstructured manner as we go along. Examples include how our build scripts are organized, our testing policy, coding guidelines.
The software is an in-house application in a fairly big financial institution.
The software is developed by a team of six people over a period of ~1 year.
The developers are consultants hired in for this project only, and will not be available to help in the future (unless the client decides to pay for it).
The client has few guidlines for how this kind of project should be documented.
I think the most important things to document are the decisions. This goes for everything from requirements to architectural choices. What are the requirements of module X? How are these requirements represented in the architecture? Why did you choose architectural pattern A over B? What are the benefits? The same goes for source code: it is common knowledge that commenting the why is way better than the how.
How you document these decisions does not matter that much in my opinion, whether you use a Wiki or a Requirements document made in Word. More important is that these documents are always up-to-date and that it is easy for anyone to access them. This can be achieved by using a wiki, or placing the documents under source control, as you say. If only a few have access to them, they are more likely not to get updated, and not to be read when necessary.
We use a Wiki for our current project and it works very well. It is easy to access for anyone (developers, managers, and customers) and a history can track changes, so you know what has been changed and why. Furthermore, we try to document the code in a meaningful way and document the major design decisions. We try not to document too much, e.g. minor things, as it is always hard to keep those things up-to-date and it is not worth the effort, imho.
Worst for me than lack of documentation is excess of documentation.
Keep in mind that yes: it's really important to document your project, but also that the major part of your documentation is always at risk of never been read at all.
So, I think that a good starting point consist in thinking of your documentation more like something that you may use to introduce new developers to your project than an over detailed description of the inner workings of your software.
G'day,
Definitely use a wiki. I'd recommend TWiki as it's an excellent and extensive implementation of a wiki without being too complicated to install and manage.
Here's a couple of initial thoughts.
Categories:
Start off with an initial ontology of what you want to capture but
allow people to add new categories or sub-categories as required,
allow people to retitle (sub-)categories as required and maybe as agreed for this one so you don't get fragmentation for multiple names for basically the same thing.
let any initial (sub-)categories wither and die if they are left empty. Do this at the end of the project as some areas may only have entries towards the end of a project.
Tagging:
Start using a tag cloud. BTW here's an excellent plug-in available for TWiki to start classifying content early on in the project. Retrofitting tags is almost impossible to do. Starting tagging early also allows people to search for information that may be there already rather than having the same info located in multiple places.
HTH I'll come back and add more points as I think of them.
First and most important, have the comments written in such a way that NDoc can parse them. This is the best way to have the code itself documented, as the developers have to change their development practices very little, and you can generate pages that explain the code without having to look at the code.
Second, getting developers to write documentation is not easy, and getting them to do it might be an exercise in futility. This is where products like Fogbugz come into play. They will help manage the development with tickets, help track check ins, and when your done an iteration, generate release notes.
In conclusion, your best bet is to find the most effective solution that fits in with the devs existing process. If it impacts their development process very little, they will be more likely to adopt the system.
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
I am going to change my working sphere from Enterprise Web Applications written for concrete business process to Public Web Sites that will be accessible to all users around.
What is difference between this two spheres at the most top level? What specific characters I need to know about modern web sites development?
I suspect one could write books about this.
I suppose the first difference is the user base. With an enterprise, you can, at least partly, ensure the users are doing what they are supposed to - and if not you know who they are and where they live. Further, they can be fired for abuse. On a public web site, you almost have to assume that some part of your user base is not there for a positive reason. So be paranoid - if they're not attacking you yet, just wait.
A second related point is that users will find ways to use (abuse?) your site you never thought of. Plan for the worst, hope for better.
Third, language, culture and usage varies across the world. A form, for example, with "zip code" that accepts just 5 digits may make sense in the US but is useless in the UK. And asking for a state and restricting it to two characters likewise makes no sense say in Italy where Italy IS the "state". This also applies to actual content - that joke you think is so very funny may be offensive in other countries. And never under estimate the ability of some folks to be offended at anything.
Fourth - get a good bunch of beta tester and test your site, and updates, carefully and thoroughly.
Fith, have a plan for scalability - if you suddenly get "discovered" can your site take the traffic.
That's 5 things at least.
In an enterprise application, functionality and efficiency trump aesthetics every time. This is because you have a captive audience. The people who use your application are being paid to use it.
However, when opening an application up to the public, aesthetics becomes more important. There are always alternatives, and a given person will be more attracted to the application which looks better. Granted, functionality is still very important for repeat users, but you won't get people in the door if your application looks amateurish.
Browser agnosticism - In enterprise apps, it used to be that the developer would target the app at a specific browser, just for simplicity's sake.
In internet accessible apps, the developer must target the vast majority of browsers. While this has gotten easier in the last few years, it is still a issue that needs attention.
Scalability - its easier to scale an enterprise app, its easier to predict the growth of usage of the app, or simply design for access by all users in the org at once. This is not generally the case for internet sites. The day you get slashdotted, or dugg is the day that you learn this. Better to design scalability in from the start, rather than have to learn it at the time that your site starts to suffer.
In addition to Zack's answer, I would say that a web site/application that is open to the public needs to be constantly evolving/refreshed in order to grow your user base and keep them. Whereas on a more closed system, consistency and reliability are key priorities.
Depending on the nature of the application, if it has significant amounts of content Internationalization and presentation of content are hugely important.
As Zack mentions, public users have a lot less tolerance for poor UI than enterprise customers do. That said, public users are more tolerant of incremental change; you can upgrade a live site as you feel like it (as long as it works, of course!!) without having to go through endless feature-request prioritization committees and user-training requirements.
Public web sites needs to be easy to use. While it's important that they look somewhat polished, don't ever let polish get in the way of ease of use. For example many designers like fixed width layouts because they are more predictable, many users like fluid width layouts because they use the space more efficiently. Side with your users.
Enterprise users can be forced to deal with needlessly-complex systems (lord knows I am more than I'd like), the general public cannot.
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 11 years ago.
An obvious answer is "an internal wiki". What are the pros and cons of a wiki used for software documentation? Any other suggestions? What are you using for your software documentation?
Loren Segal - Unfortunately we don't have support for any doc tool to compile information from the source code comments but I agree it would be the best way to store technical documentation. My question was about every kind of documentation tho - from sysadmin type to user documentation.
That's a very open ended question, and depends on many factors.
Generally speaking, if you use a language that has good documentation generation tools (javadoc, doxygen, MS's C# stuff), you should write your documentation above your methods and have your tools generate the pages. The advantage is that you keep the source of your text alongside your code which means it is orgnanized in the logically correct place and easily editable when you make a change to the behaviour of the method.
If you don't have good doc tool support or don't have access to source code, wiki's aren't a bad idea, but they're a second choice to the above.
Note: I'm talking only about code documentation here. Other artifacts obviously cannot be stored alongside code-- a wiki is a great place to put those documents. Alternatively if you use some CMS you can simply commit them in some docs/ folder as text/pdf/whatever files to be editable via the repository. The advantage there is that they stay with the repository if it is moved whereas a wiki does not (necessarily).
Tools are important, but don't get too bogged down in finding the magic tool. No tool I've found yet has a "document everything magically using tiny invisible elves" tickbox. :-)
A wiki will work fine. Or Sharepoint. Or Google docs. Or you could use a SVN repository. Hell you could do it with pens, notepaper, and a file cabinets if you really really had to. (I really don't recommend that!)
The big important key is you need to have buy-in throughout the organization. What happens in a lot of shops is they go and spend a bunch of time and money on some fancy solution like Sharepoint, and then everyone uses it religiously for about two weeks, and then people get busy with hitting the latest milestone and that's the last anyone hears about it.
Depending on your organization, field, the type of products your developing, etc., there are a few solutions to that, but one way or another you need to set up a system and use it. Appoint someone the official documentation czar, give them a cluebat, and tell them to hit people in the head everytime they say "oh yeah, I'll finish documenting that next week...". if that's what it takes. :-)
As for tools... I'd recommend Confluence by Atlassian. It's a fine wiki, it's designed to work in an enterprise environment, it has a lot of nifty features, it's customizable, it integrates well with some of the Atlassian's other nifty tools, and is basically a pretty solid product.
«Software documentation» is a very general term. There is «End User documentation», «Developer documentation», «QA Documentation». First one is usually developed by qualified techwriters. Other ones may be dynamically formed from wikis, documentation comments from source code etc. All this stuff maintenance process usually is very complex and each software company follow its own way. But there is one necessary point for all these ways: each code commiter, architect, manager, qa engineer MUST store well arranged each piece of information which may be helpful for the others. And someone else MUST keep an eye on this pieces storage and rearrange pieces if required. All this steps greatly improve all activities related to development process.
Assuming you are talking about code documentation versus user documentation, an internal wiki is great if you do not need to distribute the documentation for the code outside of your organization, to contractors or partners.
Javadoc or DOxygen is more suitable if you want distributable code documentation.
If you are referring to user documentation, you may want to have a look at DITA.
I started experimenting with a way to do user documentation with these goals:
Markdown/Html/Javascript/file-based relatively linked documents for portability (can run on local file system or you can throw it on a webserver), built-in handling of screenshots (interactively resize), and open source in case anyone else may want to do something with the crazy thing.
Your document source is written in Markdown and rendered to Html via Javascript at browser runtime.
Mandown - http://wittman.org/mandown/
We currently use inline documentation parsed by an external application (PHP + PhpDocumenter) plus various internal wikis. At times it's painful at best (mainly because only one person update the wikis or the docs...)
However, I've been looking at using ikiwiki to do internal docs. It integrate with your source countrol system (including Git, Subversion, Mercurial, Bazaar, TLA and Monotone) so all your docs track with your project. It is built in Perl and has an extensive plugin system (including multiple markup languages, with the default being Markdown). Also, the source control system is plugin based, so if what you use isn't immediately supported you could add your own. In your preferred language, if need be, since it supports non-perl plugins, too.
My company uses a variety of Sharepoint and a wiki. Sharepoint for specific documents like requirements, presentations, contracts, etc, while the wiki is used as a help guide a developer repository for tutorials on using internally developed libraries.
Yeah, we use a wiki, we also use Google documents. I find that Google documents is better than most wikis I've tried and, if you don't need to track all changes, you lose nothing. Google docs provides a good collaboration framework.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I work on a complex application where different teams work on their own modules with a degree of overlap. A while back we got a Mediawiki instance set up, partly at my prompting. I have a hard job getting people to actually use it, let alone contribute.
I can see a lot of benefit in sharing information. It may at least reduce the times we reinvent the wheel.
The wiki is not very structured, but I'm not sure that is a problem as long as you can search for what you need.
Any hints?
Some tips:
Any time someone sends information by email that really should be in a wiki, make a page for that topic and add what they put in the email. Then reply "Thanks for that info, I've put it into the wiki here so that it's easier to find in the future."
Likewise, if you have information you need to share that should be in the wiki, put it there and just send an email with a link to it, rather than email people.
When you ask people for information, phrase it so that putting such documentation in the wiki should be considered the default or standard: "I searched in the wiki but I couldn't find it. Have you put that info up there yet?"
If you are the "wiki champion", make sure other people know how to use it, e.g. "Did I go through how to create a new page with you yet?"
Edit the sidebar to make sure it is relevant to your work.
Use "nav box" style templates on related pages for easier navigation.
Put something like {{Special:NewPages/5}} on the front page, or recent changes, so that people can see the activity.
Take a peek at Recent changes every few days or week, and if you notice someone adding information without being prodded, send them an email or drop by and give them a little compliment.
As I mentioned before, a Wiki is very unorganized.
However, if that is the only argument from your developers, then invest some effort to create a simple index page and keep it updated (either do it yourself or ask people to link their contributions to the index). That way, the Wiki might grow into a very nice and quite comprehensive collection of documentation for all your work.
We've been using a wiki in some form or another for a while now, but it does take a while for people to get on board. You might find that you will be the only one writing articles for some time, but bear with it, other people will come on board eventually.
If someone sends an email around that contains information related to the project then helpfully point them in the direction of the wiki - and keep doing that - they should get the hint.
We have a SharePoint portal and use the wiki from there - we customised it with our own branding so that it "looks the part" - I really feel this has helped to improve the uptake of it.
Make sure that everyone is aware that the wiki is even more informal than email.... because there will be a "fear factor" that people may think anything they add to the wiki will be over-analysed.
I think most of the answers so far are spot on - the more you plug away at it yourself, the larger the body of useful information will become, so slowly but surely people will naturally start to use it.
The other approach you could use is this: Suggest that every time someone asks another team member a question about the project, they should answer the question as normal, but also add the answer to a section of the Wiki. This may take a few minutes extra, but it will mean that the next time someone asks the same question (which they inevitably will), you can save time by pointing them at the Wiki. This, in turn, should help people to start using the Wiki as a first source of information and help overall up-take.
You can't force developers to do something they do not have an incentive of using for; unfortunately wikis, like documentation (well, in fact wikis are documentation) rarely have any "cool" value for developers. Besides, they're already deep into dev work -- could you really bother them with a wiki?
That being said, the people who pushed for the wiki (e.g., you) should be primarily responsible for updating it, and you really would have a lot of work cut out for you if you're serious about it.
You might also try the ff:
It's not very structured you say -- a lot of people get turned off from ill-structured (hard-to-search/browse) wikis. So maybe you can fix that first
Maybe you can ask lead developers/project managers to populate it with things that are issues for them: things like code conventions and API design for your particular project
Lead by example: religiously document your part of the system. Setting a precedent may encourage others to do the same
Sell the idea of using the wiki to the developers. You've identified some benefits, share those with the developers. If they can see that they'll get something of value out of it they'll start using it.
Example advantages from What Is a Wiki
Good for writing down quick ideas or longer ones, giving you more time for formal writing and editing.
Instantly collaborative without emailing documents, keeping the group in sync.
Accessible from anywhere with a web connection (if you don't mind writing in web-browser text forms).
Your archive, because every page revision is kept.
Exciting, immediate, and empowering--everyone has a say.
I have done some selling and even run some training sessions. I think some people are turned off by the lack of WYSIWYG editing and ability to paste formatted text from Word or Outlook. I know there are some tools to work around these, but they are still barriers.
There are some areas where the wiki is being used to log certain areas, but people who update those are not doing anything else with it.
I will use the wiki to document my specialised area regardless as it acts as a convenient brain extension. When starting a new development I use it as a notepad for ideas that I can expand on as it progresses.
It would help if management would give it some vocal support, even if it is not made mandatory.
I have a hard job getting people to actually use it, let alone contribute.
One of the easiest ways to get people to contribute to a wiki, is to actually have them provide contents in a wiki-suitable fashion, i.e. so that whatever they post using their usual channels of communications (newsgroups, mailing lists, forums, issue trackers, chat), is basically suitable for inclusion on the wiki.
So that others (users/volunteers) can simply take such contents and put them on the wiki.
This sounds more complicated than it really is, it's mostly about generalizing questions and answers, so that they are not necessarily part of a conversation, but can be comprehensible, meaningful and useful in a standalone fashion.
For example a question like the following:
how do I get git to clone a remote repository???
Can be answered like this:
Hello,
Just use git clone git://...
But questions can also be answered in a less personal style:
In order to clone a git repository, you will want to use the clone parameter to git:
git clone git://....
What I am trying to say is that most discussions in a project can and should be easily used to become documentation eventually. With this sort of mindset, your documentation can actually grow rather rapidly. You only need to get people to keep in mind that useful information should be ideally provided in a fashion that is suitable for wiki inclusion.
I have witnessed several instances where open source projects started to use this approach to some extent and while some people (largely new users) complained that answers were not very personal, the body of documentation was increasing steadily, because other people simply monitored such discussions and started to copy/paste such responses to the wiki.
Basically, this is one of the easiest ways to get people to contribute to a wiki, without requiring them to actually use it themselves, the only thing that's required of them is a shift in thinking.
If the developers still need to maintain 'real' documentation (s.a. Word documents), I see no way to meaningfully duplicate that on a Wiki.
It does not make sense for people to write twice
Any duplicated data is prone to get out of sync, soon.
What my current customer has done is move all this to Wiki. So I only document once, and I do it on the Wiki.
This is okay. Working with Wiki is more tedious than with Word, but at least the doc is online and others can mix-and-match with it.
Another working solution (imho) would be to store docs alongside the source, on subversion. But then the merging system needs to be able to cope with rich text etc. as well. I don't know, if any solution for that exists (other than using HTML or LaTex, which actually would not be bad picks).
Find "sticky" items (sub-3 pg. docs / diagrams / etc) something that the team seems to be creating again and again & post it on the wiki. Make sure everyone has access to the wiki and knows its there - set up a notification mechanism if possible. With some luck, the next time they have to access, rather than dig it out of version control or their machines - they should hit the wiki.
If they still don't, try to see if the team has enough slack to actually use the wiki - Subtler issues may lie beneath their reluctance.
Take a look at the advice at http://www.ikiw.org/ Grow your Wiki
Just to add to some of the excellent advice being offered here...
As a dev in a small company that does largely gov't contract work in the 6-24 month range, I find that my time is often split between development and writing status reports (right up there with writing documentation, only worse!) Having a wiki to slap down unorganized thoughts and notes as we go along has made report-writing a lot less painful (not pain-LESS, but better all the same).
Further, if you're already in the Mediawiki world, you might want to look at SemanticMediawiki. It allows you to take the organization of your data to another level by semantically tagging it. That doesn't mean a lot on its own, I know, but I can tell you (for example) that it can drastically improve the relevance of the data returned from searches. It is definitely worth a look.
Generally good advice here. I'd like to add:
You really need a champion - someone pushing this to developers and management (without being pushy - that's a challenge!) and providing support & tutorials when possible. This person also needs to be a peer (so a fellow developer, not someone in a remote IT department) and really customer focused i.e. ready to make changes when requested.
Speaking of changes, some people here say wikis are unstructured. I disagree. Our MediaWiki installation is structured using categories, particularly with two extensions:WarnNoCategories (to require users to add a category when saving a page) and CategoryTree to show how all the categories fit together (this can be linked to from the sidebar). I've got more tips on how we keep this low threshold, if you're interested.