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.
Related
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I need a personal archive tool to archive the programming algorithms, lessons, techniques and codes.
Something like a "Personal Wiki" that supports images attachments, code decoration, content categorization and search for any content at any time.
I know i can use an open source tool like forums or media wiki but i need something customized for this personal purpose.
Desktop tool or web tool.
For those who are search for the same purpose, I found some tools:
Here are some things I've tried with their pros and cons:
OneNote
Pros
Excellent ability to organise notes. You have have books containing section groups containing sections containing pages and subpages. I've got a book for Development, then a section group for Languages, then a section for Ruby, then pages for every topic within Ruby. The highlight here is that there's no penalty to creating dozens and dozens of pages on a given topic, helping you keep things organised when you get really deep into a specific topic. It's an easy mistake to just say "Yeah, a section for Languages, then a page for PHP", but before you know it the PHP page is half a mile long and you'll never sit down to properly re-read it again, it becomes a pain to find the info you want, etc.
Great support for multi-user notebooks. It properly keeps track of who added what and what got changed when, making co-operation easy.
Syntax highlighting can be done with the OneTastic plugin, which lets you define custom styles. Just define a custom style in a monospaced font with a special colour, and call it Code.
Support for tabular data, attached files, audio, video, etc, if you need that sort of thing.
Cons
Need to use a special app to consult it, so you can't just hit it from a work computer or the like.
Web app is clunky and lacking full features, I still haven't gotten a desktop notebook to properly sync as a web app notebook.
Search isn't the best.
MediaWiki
Pros
If you make it public, you can use Google on your notes, which is better than any other search.
CSS means it's easy to style and present it how you want without manually altering every bit of text like you'd need to in OneNote.
Because it's just a website like any other, you can access it from any device without installing anything or having to log in.
Export as ePub file, meaning you can read all your notes on your Kindle/ereader, really good for refreshing.
Any page can belong to multiple categories, which is nice.
Built in syntax highlighting with code tags.
Cons
Limited/clunky ability to organise in tiers, ultimately a fatal flaw for me.
Becomes a pain to quickly add notes to pages. (I would kill for a no-page-reload transition between read/edit modes!)
Reliant on an internet connection (usually not a problem, but something to be aware of).
Plaintext files in folders
Pros
Zero learning curve/adaptation.
Read them anywhere with no special software (tip: put them in a shared Dropbox folder, map an address on your domain to that folder).
Read natively on ereaders or convert to ebook format with no real effort.
Cons
No syntax highlighting, no image/audio/video media, no tabular data.
Hard to fuzzy search.
Edit conflicts if you're studying alongside someone.
Google Drive
Pros
Excellent support for sharing/co-operation
Good search
Good mobile support
Supports a lot of media
Cons
Tends to be slow to use
Presentation options tend to be frustrating
Reliant on internet connection
My personal recommendation: OneNote + Onetastic plugin, using all tiers/dividers, exported to PDF or multiple PDFs regularly so you can consult them from elsewhere.
Quoted from this link:
https://www.reddit.com/r/learnprogramming/comments/3acusr/how_to_take_notes_while_learning_programming/
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 2 years ago.
Improve this question
I try to be very cautious with this question. There are at least three different web-development frameworks available in Smalltalk. The most prominent seems to be Seaside but there is also AIDA/Web and Iliad.
They seem to be very similiar, but this impresson may be wrong. I wonder who has tried the different tools and can share the pros/cons of the different packages.
A more concrete question would be, do yo know of let's say any software in the bookkeeing area which has choosen to use either of the three (or other) web development frameworks.
Here's one other question. What about maturity and compatiblity. Which framework can one judge as the "most" stable?
99% of my practical experience is with Iliad, so my comparison is primarily about how I got to choose Iliad instead of the others.
Seaside. Tried it first, it is the most known and the first you stumble in. I found it hard to understand (as always, no matter what you use, when it gets to real implementation you always run into issues that fit badly with the general theory), there was little documentation around and the community seemed to care little about telling n00bs how to grow up. I eventually dropped it to check Aida. You find them here: http://seaside.st/ and on IRC at #seaside
Aida. I really liked it, as Janko is extremely patient and supportive. It is large, though. I decided to use it, when I was to start implementation for our project and it was only by chance that I ran into Iliad a few days before starting. You find Aida here: http://www.aidaweb.si/ and on IRC at #Aida
Iliad. The main reason I chose it was that I had just dropped Squeak and switched to gnu-smalltalk. gst seemed to have a lot of ongoing activity on Iliad, so I reckoned I was probably going to get a better assistance with it. It is much smaller as a concept (though it does absolutely everything) and I had very little trouble in getting started and in tweaking it to what I needed for. It also proved to be well managed, as I went thru 3 releases without ever being in trouble with what I had already deployed. You get answers to questions usually in 12-24 hours max, which is fine for me. You find Iliad here: http://www.iliadproject.org/index on IRC issues are usually channeled on the #gnu-smalltalk channel
What we are doing is a GUI for a PostgreSQL database used to manage a large multimedia dictionary, that in turn produces content (among others, for KDE-edu). I have no notion of booking apps in general, so I cannot answer to your question properly.
Yet, speaking as an analyst, a booking app is mostly a DB with an online GUI, so I see no reason why you could not make it. Much will depend on how easily your db can translate into objects. You could use a RDBMS, as we did, and design tables to map objects, or use an OODBMS. Both solutions have pluses and minuses, none of them is going to have an impact on your choice of framework, I'd say.
My suggestion is that you take a month or so in making experiments and see what better fits you. I don't think there is a tool that fits everyone, we are all different and what is easy for me may be hell for someone else (and the other way round, obviously). So try your car before buying it ;)
I would not invest too much time in studying the general theory. Using a smalltalk framework is going to turn upside down the way you make a web app anyway, and your first contact is going to be full of "false friends" you inherit from previous mindsets. Your best asset is definitely going to be "how quick can I grasp what they tell me", and this is largely an individual thing, depending on you and on who you bump into. So I'd really suggest you get your hands dirty BEFORE reading too much theoretical stuff.
These frameworks are all quite different and have different goals. It would be interesting to collaboratively create some kind of comparison.
As an author of Seaside I can provide the key properties of Seaside only:
Seaside makes building web applications feel like composing traditional GUIs: components can be freely composed and reused. Sequences of components are defined using a sequence of Smalltalk statements.
Seaside has a layered architecture, providing you with high-level abstractions (components, control flow, callbacks, HTML generation, JavaScript generation, ...) over low-level concepts (HTTP, Request, Response, URLs, HTML, JavaScript). If you need to, Seaside gives you full access to low-level constructs too.
There are two Seaside books to help you get started: Dynamic Web Development with Seaside and Seaside Tutorial.
Seaside provides a tight integration into various state of the art web technologies: JavaScript (JQuery and JQueryUI), SVG, RSS, HTML5, Comet (Server-Push)
Seaside runs identically on most today's Smalltalk platforms: Pharo Smalltalk, Squeak, GNU Smalltalk, GemStone Smalltalk, VW Smalltalk, VA Smalltalk, and Dolphin Smalltalk. It is supported by all vendors of Smalltalk platforms.
Seaside provides industry proven open-source components for meta-modeling (Magritte) and content management (Pier).
Let me introduce some strengths of Aida/Web too, because as its author it would be hard to me to compare with other two frameworks. Aida strengths are:
RESTfull URLs
MVC support, every domain object can
have its own RESTfull URL, each domain class has its own web presentation class,
Integrated AJAX and Comet
support, you don't see any difference
between a traditional and Ajax
programming anymore,
Tree-like control flow for GUI-like
control flows, without need for
continuations
Building web pages programatically by
composing from components/elements
(no template based)
Scalable in complexity and performance
Integrated security with access
control and users/groups management
Ported to most Smalltalk dialects:
Squeak/Pharo, VisualWorks, Gemstone
GLASS, Dolphin, Smalltalk/X
Prime and most fresh example of Aida at work is this year Smalltalk Google Summer of
Code site.
This is the is a nice example because it was developed it in maybe a week in
total, together with a development of GSoC process in parallel and in
the same time managing that process as an admin. This site is actually
an extended Aida/Scribo CMS, with strong use of so called scriblets,
that is, dynamic web "includes" directly into the content of the site.
That way I was able to very quickly support the new ideas which come
during the evolving GSoC process.
Well, Suixo uses Seaside. Take a look at the GSoC projects we defined. Its more ERP than bookkeeping, and currently focused on healthcare.
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 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/
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.