Hot answers tagged

46

Direct answer to your question: Yes. Wikipedia has tons of non-IT editors. Longer answer: Your IT vs non-IT distinction here is a red herring. All people, IT or not, will still ignore a wiki if it isn't presented to them as something they should care about. Introducing a new data management system is always non-trivial to sell to people because you always ...


12

Is WIKI really appropriate to store document for software development? Instead of writing docs, pdfs and other kind of files, why don't you unleash the WIKI's full potential as a collaboration tool? You can write your documents there, attach your diagrams and even better: if you use Fitnesse, you can turn your wiki pages into really useful and living ...


11

It depends on the wiki software. Generally non-IT people will prefer a wiki with a WYSIWYG editor and might not like wikis which require any kind of markup editing, even if the markup is very simple. For your bonus question: MediaWiki does not provide a native WYSIWYG editor. You can see which ones do in Comparison of wiki software.


9

Yes, that's sound a good solution, if you organize the page in a simple structure, easy to browse. Choose a wiki with a simple syntax. ( Dokuwiki is a simple one and not require a DB ) Edit: if you use a version control system, that is SVN or BZR, try Trac, where you can define milestone, keeping bug and features request, and define your own workflow to ...


9

Don't focus too much on getting a perfect structure up front, better let it grow organically. It's the communication culture and process that matter. Below are some tips to maintain team wiki. fundamentals value feedback Ask for, collect and record any feedback you can get - mail, wiki page comments (most convenient btw), messenger, conversation. ...


8

Having all documentation in one system instead of two can be a real advantage. Things like backup & restore, versioning, global search, global search&replace, cross-linking, and, as you wrote, putting all docs in one final document, will typically work with less "friction" when you don't have to maintain two different systems with overlapping ...


8

Since multiple answers point to Trac as a suggestion I'd like to suggest a similar, but better in my opinion, alternative: Redmine. Redmine is a project management solution, including Wiki, Document Repository and version control integration. It's also written in Ruby on Rails and way easier to extend and hack than Trac, in my experience. More than ...


6

We're using LaTeX and SVN. Since LaTeX documents are just text files, it plays well with version control, unlike some binary or partially-binary formats. You get all the advantages (and disadvantages, admittedly) of version control you're used to from using it with your code. LaTeX takes a little setting up (to define your own styles/class), but once you'...


6

In my organization, we have a very successful wiki implementation. It is based on MoinMoin, which is a Python wiki package. To make it successful, however, it took years of dedication in staff training and singing its praises. For an organization of around 80 full-time employees, I had to hold a number of beginning and advanced training sessions, plus spend ...


5

I think that a wiki can be a great approach to the organizational problem you're facing. I also believe that non-technically oriented users are very capable of learning the wiki features with some caveats. I agree wholeheartedly with the comment about user acceptance being vital. You are more likely to face the "I'm not going to use it" or "It's just ...


5

Two types of answer Pessimistic view Corporate ordinary employee is lazy, passive, lowbrow executor, not interested in quality work, only in quantity. If he know Office, he haven't interest to know and use more Realistic view Contrary to code, historical aspects of "active" documents have a lot less value - every time only "now state" make sense in ...


4

Personally, I really like Tiddly Wiki. It has a pretty complete wiki syntax, is a self contained single html file and works well with a variety of web browsers without the need for a server. It even has an extensible plugin architecture which allows you to add plugins to do all sorts of interesting things like encrypting tiddlers or adding footnotes.


4

There are various "single source" solutions for documentation out there. A number of teams I've worked with have had great success with Madcap Flare. I especially like how it integrates well with source control and provides support for creating context-sensitive help. Full disclosure: I have NO relationship with Madcap, not even as a reseller. But I have ...


4

Some wikis (eg. Ikiwiki) have the ability to store their data in Git, as you mentioned. Given that, you can link the documentation as a Git submodule under your regular source repository. With the above setup, pulling the source and updating the submodules would pull the latest copy of the documentation. Offline, you can edit each one at will. When you ...


4

Yes, wikipedia proved it. It require users to comply anyway, which isn't always easy, even if it is in their interest. People will resist to change.


4

Use Code Documentation, first. Add Wiki & other methods, if possible I know, that is going to be difficult, to maintain it. Practical answer: In practical terms, the first thing that developers do, its check the code. As a developer, I like to have external documentation, like Wiki (s), manuals. But, the first thing I do, it's to review the code (...


4

First, it is important to choose a good Wiki. Choose one that: Is well maintained and has good support. Supports user authentication and has access control on documents or namespaces. Tracks changes to documents and provides a history. Allows E-mail notification of document changes. Has a good editor, preferably WYSIWYG, and supports lists, tables and ...


4

Whenever possible, reduce or eliminate the need for documentation by writing clearly understandable code instead of writing documentation to explain obtuse code. Keep the documentation as close as possible to the actual code it describes. In most cases, that means putting the documentation in the code itself. Some development platforms (e.g. Visual Studio) ...


3

It makes sense to store the documentation in the same repository as the source code. Sphinx seems like a good option to me. it takes reStructuredText files as input, which is easy to edit and diff it generates hyperlinked output (HTML, PDF, ...) you can reference your source code (Python, C, C++, JavaScript)


3

I do see a drawback to using MediaWiki: it can get quite complicated and does take some time to learn. It can be overkill for your documentation needs. My company is using the wiki that comes with Google Apps, which is very simple to use, and has a WYSIWYG interface. However, you do loose out of some of the categorization that comes with MediaWiki, ...


3

As an addition to everything mentioned here - I'm afraid you will have to spend some time setting up the structure, collecting documents and uploading, sorting, and tagging them. I used to try to convince people to use these or that pieces of software or technologies, like Jabber conferences, adblock rules, pieces of JavaScript code, certain window managers,...


3

There is a database of wiki patterns and wiki antipatterns on Wiki Patterns. Still, my experience with wiki usage in projects was not so successful. People were quickly frustrated with the wiki usage in the beginning, because it required effort to maintain and to update articles. Then there were fights about who should organize the structure of the wiki, or ...


3

For Microsoft platform, TFS (Team Foundation Server) integration with SharePoint is just what you're searching for. By creating a new team-project, you can choose a template encompassing almost every aspect of software development process. It gives you a portal in which you can define team members, assign their roles and security permissions, upload, share, ...


3

I totally agree with Simon Stelling on his points. Trac is a great tool that I've used several times for having nearly every aspect of a project in a centralized location. However, there are other tools out there. Another tool that you can consider would be Redmine. For some of the features that you want (such as portability), you'll need to customize it ...


3

Robert Harvey's answer is already a good one, but I like to add a reamrk about your current plan. The same way your code changes from release to release, the same way your documentation has to change. But if your docs are in a Wiki or a "Stack Exchange" like system, you cannot integrate this well into your version control system (VCS). So I strongly suggest ...


2

I can recommend Trac. Regarding your requirements: Portability: The syntax used is fairly standard and there exist tools to get the wiki articles exported. Easy to use: The system is very intuitive to use. Images are supported, the syntax is easy to remember and feels natural. There is a WYSIWYG mode where you see the formatted content while you type ...


2

Trac provides an interface to Subversion, an integrated Wiki and convenient reporting facilities. http://trac.edgewall.org/ But I don't know about your installed stack.


2

Don't feel obligated to use it, but I would use it for documentation. Another possible use could be for collaboration on feature ideas, though wikis aren't exactly the best tool for that.


2

A wiki is a good way to go. I think it would be best if the documents were still versioned. You can have floating documentation that keeps with the most current features. Still take snap shots that way it is easy for someone looking back to find documentation for that software three versions ago, without having to look through the document history, which ...


2

At one company I have worked at we had a lot of success in using a Wiki as a repository for technical documentation. We tried getting the stone age business analysts to start using it for our benefit as well but alas, anything that would make them more accountable for out of date requirements documents or provide more transparency to their little fiefdom ...



Only top voted, non community-wiki answers of a minimum length are eligible