I have to develop for a small organisation an internal Knowledge Management platform,
enabling the staff to :
get an overview of the organisation, roles, responsibilities ;
share administrative and technical processes ;
write and share articles (mainly about researches) ;
share quickly practical information ;
upload and share documents.
I was really interested in semantic wikis, because they can provide powerful linking between the different articles, writers, documents... and that way enable the workers to browse from a page to a related one smoothly.
However those people are not computer engineers and I am afraid that including semantic data in their articles wouldn't be possible. They need something user friendly and WYSIWYG if possible.
That way :
do you know user-friendly semantic wikis ?
do you know other tools that would enable this powerful browsing, linking automatically related contents ?
Thank you for your advices.
I would recommand the use of the Semantic_MediaWiki MediaWiki extention in combination with
Wiki Editor WYSIWYG Editor.
You can embed the wikieditor (or basically any other WYSIWYG Mediawiki extention by using the following code:
! WYSIWYGField:
| {{{field|WYSIWYGField|input type=textarea|editor=wikieditor}}}
Related
I have not used either of them till yet. I looked at their websites and found their brief descriptions:
Github Gist:
Instantly share code, notes, and snippets.
Pastebin:
Pastebin is a website where you can store any text online for easy sharing. The website is mainly used by programmers to store pieces of sources code or configuration information, but anyone is more than welcome to paste any type of text. The idea behind the site is to make it more convenient for people to share large amounts of text online.
Apart from the explicit mentioning of "anyone is welcome to paste any type of text" in Pastebin's description, I see no difference in what they are used for.
I'd appreciate if someone could point me the differences between them.
Gists are way more 'advanced', since Pastebin is very simple and user-friendly.
At very least, gists are used to be shared mostly with coworkers, while pastebin is heavily being used for wide-usage or for private usage.
https://help.github.com/articles/forking-and-cloning-gists/
Is there any obvious way of sharing Styles - as set in the Layout/Style panel (EA13) - between EAPs? Seems like an obvious simple feature that should be in the tool somewhere, but if it is I just can't find it!
Thx.
Not directly. The best you can do is to extract them from the registry. Unfortunately this is documented nowhere and the used keys are spread all over HKEY_CURRENT_USER\Software\Sparx Systems.
You might also ask on Sparx' forum and hope for one of the supporters to read and give a better answer or to send a mail to Sparx' support.
Given a project I'm about to start there will be documentation produced.
What is the best practice for this?
Should the documents live with the code and assets or should there be a separate documentation store?
Edit
I'd like a wiki but I will need to print the documents etc... It's a university project.
It really depends on your team. Where I work, we keep documentation in a wiki which is linked in with our team website. For the purposes of shipping documentation, the wiki can be exported and we run it through a parser that "fancifies" the look and feel of the documentation for customer purposes.
Storing the documentation with the code (typically in your source repository) is not a bad idea. Just make sure to keep them separated. For example, keep a docs folder which is on the same level with your src folder in your repository. This way, you can quickly ship the current documentation, you can easily track revisions, and anybody new to the project can immediately jump in without having to go to multiple locations for information.
Storing it in source control is fine.
This is an interesting question -- basically, what others are saying is right about generated documentation, source files and templates/etc. should be stored in source control and generated during your build process.
As far as requirements/specs/etc. documentation, I have worked both ways, and I very much prefer using SharePoint or a Wiki/document portal that is designed for document sharing/versioning. The reason is, most non-developer folks aren't comfortable working with source control systems, and you don't gain any of the advantages of intelligent merging if you are using a binary format like Word. Plus it's nice to have internet-based access so you can reference and work on the docs in a distributed team without people having to install extra software.
Here's a 2017 summary of the options and my experience:
(extreme 1) Completely external (e.g. a wiki, Google Docs, LaTeX, MS Word, MS Onedrive)
People aren't bothered about keeping it up to date (half of them don't even know where to find the page that needs updating since it's so out of the trenches).
wiki platforms are “captive user interfaces” - your data gets stored in their proprietary schemas and is not easy to examine with a simple text editor (Confluence is even worse in that you have no access to the plaintext content at all anymore)
(extreme 2) Completely internal (e.g. javadoc)
pollutes the source code, and is usually too low level to be of any use. Well-written source code is still the best form of low level documentation.
However, I feel package-info.java files are underutilized.
(balance) Colocated documentation (e.g. README.md)
A good half way solution, with the benefits of version control. If a single README.md file is not enough, consider a doc/ folder. The only drawback of this I've seen is whether to source control helpful graphics (e.g. png files) and risk bloating the repo.
One interesting way to avoid this problem is to use plaintext diagram tools (I find Grapheasy and Text Diagram to be a breath of fresh air).
plaintext can be easily read even if your rendering engine changes as the years go by.
Github's success is in no small part thanks to its README.md located in the root of the project.
One tiny disadvantage of this approach though is that your continuous integration system will trigger a new build each time you make edits to the README.md file.
If you are writing versioned user documentation associated with each release of the product, then it makes sense to put the documentation in source control along with its associated product release.
If you are writing internal developer documentation, use automated internal source code documentation (javadoc, doxygen, .net annotations, etc) for source level documentation and a project wiki for design level documentation.
I think most of us in the industry are not really following best-practices and it of course also depends a lot on your situation.
In an agile environment where you would have a very iterative process of release, you will want to "travel light". In this particular case, Jason's suggestion of a separate Wiki really works great.
In a water-fall/big bang model, you will have a better opportunity to have a decent documentation update with each new release. Also you will need to clearly document what version of the requirements was agreed on and have loads of documentation for every tiny change you do to requirements (due to the effects it has on subsequent stages). Often if the documentation can live together with the version controlled source code it is the best.
Are you using any sort of auto-documentation or is it completely manual? Assuming that you are using an auto-documentation system, the documentation is more or less generated on the fly, and would be part of the code itself.
To me, (assuming that it's possible with whatever code you are using), this would be the preferred method of handling it, as you wouldn't need to maintain the documentation source at all.
i just want to know about the files and folder structure for a site which is a plugin oriented like wordpress or joomla.
my requirement is to develop a site and want to add more functions via plugin or something like features.
what i need is to just add and additional information or functional sessions like in wordpress
we can use All in one SEO packages it will bypass the title and some other information.
or some other features like Related articles are shown at the bottom of a particular article body.
aam talking about a structure of wordpress.
does any one have an Idea please share with me.
hope every one understood my qustion as well.
thank you.
I think there are many possible solutions.
It might depend on:
scalablity (how large do you want it to support plugins and do the reuse parts of each other?)
vibility (how should the plugin address become visible in the url?)
deployment (who can add new plugins? is it open for everyone or just certified developers)
You could go for:
www.domain.xyz/plugins/some_module/
But what if the plugins arent plugins but becomes default part of the system afterwards?
Then it would be more logical to call them what they are like:
www.domain.xyz/some_module/
But then you might get into problems with plugins name like exisiting system folders. Therefore you would need some "reserved" list of foldernames to prevent that.
You could also go for:
some_module.domain.xyz/
But that would requiere your webadmin or webserver to support multiple aliases for one website on the other hand, this arhictecture would bring scalability, because you could move the modules to other webhosts later on. But its also more expensive work in the development + its hard to make it "user/developer controlled" as this could grow.
You could have a look at how FaceBook is handling Applications too. Thats a plugin interface too. Slow, but implemented.
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
The people writing the user manual are not necessarily programmers, and they need a visual editor. A major issue is the internal format of the authoring tool; it should be readable text/html, so it's easy to compare versions of individual pages checked into version control.
DocBook
(source: docbook.org)
Microsoft HTML Help Workshop can be used to create good quality professional CHM help files. All you need is a bunch of HTML files. The tool "compiles" all these and bundles into a single Help file.
The HTML files can be generated using Microsoft Word/Frontpage or even Dreamweaver. You might want to consider source controlling these HTML files.
Latex. Lyx provides WYSIWYM for writing latex files.
At my old job they used a tool by madcap software called flare.
It seemed to work really well.
There are other professional products which allow help file writing and they have support of "context ID" which makes context sensitive help possible. Doc To Help and RoboHelp are these type of products.
A good combination to consider is Subversion, DocBook and Publican.
Version control = Subversion
Content Authoring = DocBook
Publishing = Publican
Optional WYSIWYG = Serna
At the moment, this is one of the toolchains in use by the world's largest provider of open source solutions, and the name behind much of the world's use of Linux-based operation systems in the enterprise market. Most (and close to all) of Red Hat's official documentation is created in such a manner. Same goes for Fedora.
The major "pro" here is that these are freely available tools, with a strong overlap in the market of technical writers. All of which will be able to (but might not want to) write in XML, and picking up DocBook is like picking up HTML in the 90's. Subversion is a very common version control tool, that like DocBook is relatively easy to implement and use. Publican is a great publishing tool that can take DocBook XML, and publish it to PDF, HTML, HTML-single, etc. Obviously your writers can use a WYSIWYG like Serna, but I use snippets in Geany (on Fedora) or TextMate (on OS X) personally.
The major "con" is the perception of technicality. Your writers might want WYSIWYG (and can have it), and depending on your documentation needs, this might be what you end up using. As you would know, there's a market out there for "Technical Writers" who specialize in fixing Microsoft Word styles (and markup), so the arguments for separating "authoring" from "publishing" are based on proven but distinct use cases for organizations that require documentation to be held up to the same standards of the engineering/programming/source production.
Some of the extreme advice you will get comes from people and companies that have been exposed to the value of XML documentation, and especially those in the realms of DITA, where certain multi-nationals have a reputation for acquisitions that are influenced by the format and availability of the product knowledge. there are also the arguments that locking your documentation into a "sticky" or closed format doesn't help the future maintenance requirements. This is where the open source options gain support on a corporate level. Plus, obviously, it's free.
You can use Subversion and MGTEK Help Producer. Help Producer makes help files from Word documents. TortoiseSVN comes with scripts to compare different revisions of Word documents, in Word itself (Word has a version compare tool).
Your users are going to want a visual diff tool that resembles the one they are editing in. If they are just slightly not-technical, DocBook or Latex aren't going to work (I've tried giving my users both, and I even tried Epic Editor as a DocBook editor which is very expensive but didn't work out very well after all). Sticking to something they know (Word) will prevent you many headaches.
I was very reluctant to go this route at first too, because I wanted a solution that was more 'technically perfect', but I realized over time that having happy and productive users was more important. Just saying that I know where you're coming from, but try the Word route - it works much better in practice than all the 'pure' text-based solutions that are out there. Regular users don't like markup based editing.
If you're using Visual Studio, take a look at SandCastle - http://www.codeplex.com/Sandcastle.
There's also a couple of tools that help you build sandcastle files, try searching "sandcastle" on codeplex. One of them is SandCastle Help File Builder (http://www.codeplex.com/SHFB), but I've never used it so I don't know if non-technical users will be happy with that.
Mapcap Flare is the best commercial tool around. Written by the ex-developers of Robodoc
I created a documentation system called Mandown (Markdown/Html/Javascript/file-based relatively linked documents for portability) which would easily go under version control. The visual editor part you would have to figure out separately - I sometimes use HTML-Kit which at least has a preview feature.
See What is the best way to store software documentation?
Here's another tool to check out: Xilize
We are using APT. It integrates well with the CI (standard build artifact) and is more alive than for instance word document. It is also possible to generate PDFs and other formats when needed.