Using MSword (or word from open office) is a problem because we can not compare and merge different versions of a same document especially if more than one person is working simultaneously on it.
The problem is not just MSword (it has some limited functionality to do compare and merge), any tool which produces non standard text file document is hard to use because of compare and merge. Additionally it is not nice to put binary format files into repository, but let's assume this is just an optimization of repository size issue.
From the other hand it is not nice to have plane text file for reading.
One possible solution is to use HTML files. They are plane texts and you can do a lot with them. They are easy to read, but the problem is that they are not nice to write.
One possible solution is to use text file with some special format, which can be easy to write and will be easily converted to HTML. HTML is chosen, because everyone has an easy way to read it by simply use favorite browser.
There is one common well known thing which does exactly this - Wikipedia. It provides simple text based syntax which is converted to html on Wikipedia server.
There are several tools which provide wiki like output, but has slightly different format. MediaWiki is the original one, which is still used to power Wikipedia and it will be better to use it's format.
There are some addons to MediaWiki, like:
MediaWiki is web based, which means in order to use it one shall start MediaWiki server and keep all wiki pages there. This is very useful if many people has to use it from different places.
When using it by limited number of users for internal documentation web based approach is disadvantege becasue:
One possible solution is to have standard text files (in UTF-8 encoding) with MediaWiki format. For visualization use a simple program which converts wiki text files to html and then use favorite browser.
Using such a solution we can:
Using MediaWiki as a format means:
Wiki content (in MediaWiki format) is written in standard (UTF-* with or without BOM) text files. One proposal is to have following folders:
-+ | +- wiki - folder (with all wiki files inside) | +- image - folder with all images (if we have images) | +- html - folder which is empty and is excluded from repository, there all html files are generated | +- dot - folder where all generated .dot files will go | +- svg - folder where all generated .svg files will go
YwikiCmd program is started on .wiki files to get .html representation. For the (human) reader it is easy to get html, just start some YWiki with some parameters and get resulting htmls. Then simply click on some of them and read them.
For writers it is a little bit more complicated. If writer just writes text into wiki, then there is nothing else to do, but usually writer likes to see changes quickly into html. In order to have this in better way it will be nice if it is possible to have followin:
If above is available then one can edit file in text editor and looking at corresponding html on browser at the same time. When .wiki file is saved it is automatically converted to html and browser immediately re-renders newly created html. Which effectively means in 1 - 2 seconds after save author will see changes in web browser.
There will be some tools (.exe files) needed, which has to be in some known place. This tools are activated from some .bat/.cmd files from a folder containing all other folders. There are 3 possible ways to have .exe files reachable by .bat/.cmd files, put all needed tools in:
pathtoolsdir)First approach has advantage to have everything in one place (and even easy to put new versions of tools), but if this tools are used from many places then it is not very nice.
.bat/.cmd files are created in such a way that if there is definition for toolsdir then it will be used,
otherwise .exe files will be started without path which means they has to be either in current folder or somewhere on path.
To convert only changed .wiki files we can use make files.
There is an example for this using Microsoft's nmake tool.
A doWiki.bat will start nmake tool which will
convert any changed or new .wiki file into .html file.
nmake was selected because it is very small stand alone tool which every developer (mmmm, VisualStudio developer) has.
A batch file is doWiki.bat
Auto converting .wiki to .html is done currently by using external program which
will register for changes in wiki folder and start doWiki.bat.
This program is a free open source solution in C# and is available at https://github.com/benblamey/when_changed
To get pre-compiled .exe: http://benblamey.com/downloads/when_changed.exe
There is a plug-in for Firefox (perhaps it exists for the other browsers too): https://addons.mozilla.org/en-US/firefox/addon/auto-reload/?src=api Simply install it in Firefox and maybe additionally uncheck annoying notification on reload: Tools-Add-ons->AutoRelaod->options->show notifications
For chrome one can use extension LivePage: https://chrome.google.com/webstore/detail/livepage/pilnojpmdoofaelbinaeodfpjheijkbh?utm_source=chrome-app-launcher-info-dialog
After installation you shall enable it to be able to read local files (if you do not do that it will complain when trying to use it on local file and will guide you how to enable it).
I have changed in LivePage option to check for changes once per second (default is 200 ms).
After loading some local file which you want to auto refresh - click on blue globe in upper right corner.
MediaWiki is: http://www.mediawiki.org
RAM
Maindmap