Add user generated comments to existing javadoc - documentation

Our team develops software for BlackBerry devices. The BlackBerry API (javadocs) is poorly documented, and sometimes even outdated.
What we would like to do is import this existing documentation into an online system that could then be edited/commented by developers/users - thus creating a far richer user generated API documentation. Maybe we can even add sample code / references to the appropriate methods.
Is there a simple way for doing the above? Any available commenting systems that can integrate with javadocs?
I have done extensive search for a solution on the internet but couldn't find any available software solution to this problem.

Related

Polarion testing reports. What is the best way to build dashboards and live reports?

Where do you find knowledge about Polarion testing reports?
Are you using external adviser? Documentation? Videos (find only few)
Or have you been just doing "play and learn"?
That is a very broad question.
One of the best ways is to study some extensions from the extension portal and to study the extensions from the sdk. There is a custom widget example available in the SDK.
External consultants are, depending where you are, also a good, but more pricier alternative.
The SDK Documentation is quite good, at least ok.
A good entry is ITrackerService and IWorkItem objects. For testing you will need additional ITestManagementService and ITestRun
If you want to setup and configure the system by yourself you need to "play and learn", otherwise it is clever(but costly) to let a external consultant do the job.

Evernote API in Unity3D

Since I haven't got any response on the Unity3d or Evernote forums, I'll try it here.
The last year I have worked a lot with Unity3D, mostly because the good integration with the Vuforia Augmented Reality library and the fact that publishing for multiple platforms is a piece of cake.
Now I want to show notes in an AR setting and am looking at the Evernote API for this. I couldn't find anything about using this with Unity, I can see why this is not the most common combination.
My question is: do you think I can access the Evernote API through Unity? If so, how should I do this? Or is it for this purpose perhaps wiser to make (parts of) the application with Eclipse/xCode?
Hope to hear from you!
Link to Evernote API: http://dev.evernote.com/doc/
The Evernote API has a C# SDK which you should be able to call through Unity. In terms of how to do it, you will probably need to download the SDK and follow the instructions yourself. Their github seems like a good starting point.
One thing to note is that Unity's .Net library for mobile clients are quite limited and with webplayer you will need to deal with sandbox security issues. But start with the standalone build first and see how you go

Ideal UI markup language

A friend of mine and I are looking to start a project looking into accessible user interface (for blind users) design. There are a number of projects making existing GUI's accessible by tagging them with audio information but we're looking to work from the ground up and actually take input from a ML and create an accessible application.
I'm trying to figure out what ML to use and am torn between three at the moment. The three I'm considering are XAML,MXML, and XUL. Currently, I'm leaning towards XUL because it's open but I was wondering if anyone could think of any pros/cons that I might be missing? I know that XAML is the most popular but does it do things that XUL can't? How similar are they?
I should add that whatever ML we end up using we will be extending the syntax so that we can provide additional information to the audio system.
I have already addressed this question to some extent here.
The pros/cons of XUL are:
it's open
it's cross platform
it's well established with a large community
it still basically has to be run in a browser that supports XUL (firefox)
one of the comments from my question stated that XUL is a bad choice because firefos is buggy
The pros/cons of XAML are:
it'll work on Windows/Mac
it has a well established drag-drop IDE (VS 2010) to create GUIs
it has a massive support community
it's closed source
it's a closed platform, IE. it not an open standard (not covered under ECMA like .NET and C#)
there are legal issues regarding the use on non microsoft/mac plagforms (see my post)
it requires either a browser with a the silverlight plug-in or the .NET framework to use it on the desktop
it's developed/controlled by MS. This isn't an attempt to troll. Seriously, look it up on google. There are a lot of people who are suspicious of MS's intent behind creating XAML and it has garnered a lot of negativity behind the platform. It might be worth taking into consideration.
The pros/cons of MXML:
it's cross platform
it's closed source
it runs on a closed platform
it requires adobe flash (which, a lot of people claim is a dying platform now that Apple is rejecting to support/allow it).
it requires a browser with a plug-in
Note: I can't really say much about MXML because this is the first time I've heard about it. I just pointed out the obvious pros/cons for completeness. I'll have to research it and add an entry to in the question I linked.
XUL application can be run under XUL Runner because after Firefox 4, remote XUL application execution within Firefox browser is prohibited

Software Engineering Component Repository Tool

I'm working as a software engineer for a company. We are going to apply some software engineering standards in our development process. We need a tool which provides a repository for our peripheral products (functions, classes, libraries, ...) which is created during software development process for later use. The tool should provide some functionalities (e.g Name of the component, it's functionality, withing which projects it is used?, author, publication date, list of known bugs, user rating, comment, ...) and it's better to have a web-based interface. Does anybody know such a software?
You should check out FogBugz. Its a great project management tool which has recently released Kiln which is source control you can integrate with your projects.
A cheaper alternative is to look at something like XP-Dev.
In my experience, such a tool doesn't exist because the problem is solved differently. Companies typically use component frameworks, whether their own or 3rd party, and develop new components that conform to the component standard from their framework.
Each project then depends on the framework rather than on specific versions of specific components. This also resolves interdependencies and all related version compatibility issues.
Component framework is typically documented somewhere by its vendor and newly created components can be added to your company's wiki, such as mediaWiki.
Alternatively, the company may need some knowledge management. See the introductory videos from kbPublisher. kbPublisher is an OpenSource Knowledge Base which may be even more suitable than a groupware like mediaWiki. The free version of kbPublisher can be downloaded here.
Note each project should have a feature which displays the framework version number and configuration, as needed by staff. This way, when you are targeting a particular client, the system can be identified remotely.
Open source tools like GIT or SVN may provide source code management however they may lack in the functions you are asking particularly bugs or ratings. There are also many paid tools available in the market which not only provides source code management but also management and integrations over projects. You may explore:
TFS https://en.wikipedia.org/wiki/Team_Foundation_Server
Rational Clear Case http://www-03.ibm.com/software/products/en/clearcase

Software/Platform to Share Specs

What are the software/ Wiki you use to write and share your specs about the developers, testers and management?
Do you use Wiki system, and if so, what Wiki software you use?
Or do you use Sharepoint to manage and version the specs? One problem with SharePoint 2003 as specs platform is that it's very hard to collaborate among different people.
For backward compatibility sake, I would also like to have the platform able to import Microsoft Word seamlessly. And it would certainly help if the interface is similar to Microsoft Word.
Any idea?
I've used Confluence at a number of places, it's a pretty powerful wiki and very good for creating specifications that can be shared amongst various parties. See:
http://www.atlassian.com/software/confluence/
There's some more information here on the advantages of using Confluence:
https://stackoverflow.com/questions/170352/confluence-experiences
EDIT: I've updated this to deal with the Microsoft Word import feature you mentioned. Confluence supports this through the Office Connector here:
http://www.atlassian.com/software/confluence/plugins/office-connector.jsp
There's also a Sharepoint connector:
http://www.atlassian.com/software/confluence/plugins/sharepoint-connector.jsp
plus a whole bunch of plugins:
http://www.atlassian.com/software/confluence/plugins/sharepoint-connector.jsp
Some of these are user contributed also. I can't recommend Confluence enough as a commercial wiki.
I've also used JSPWiki, which is open source. it's ok but not as good as confluence, see:
http://www.jspwiki.org/
You could try Google docs - I have successfully used this in the past. It supports import / export to MS Word, and it has great support for multiple user - see http://www.brighthub.com/internet/google/articles/8236.aspx.
It supports versioning, allows you to chat with other people who are currently working on the document, and shows you a list of all the changes others have made to the document (without needing to close / reopen the document).
If you want corporate support, Google also provides that - see Google Apps for business.
We use SharePoint -- it's not ideal, but it does a decent job. If I were you, I would seriously look at getting off SharePoint 2003 and on to MOSS (SharePoint 2007). It's not perfect, but it's substantially better. Here's a little bit on using MOSS as a wiki. I think in general wiki's are a good tool for getting people up to speed on your system. We used to pass around "getting started documents" and now we have all that type of stuff in our developer portal.
Per John's comment, I looked up this feature comparison. I have to go back and look at what features I'm using that are not in WSS -- I might be paying for licenses I don't need! :)
We use email. I know it isn't elaborate, but it is easy to use. Everyone has it installed and there are no licensing issues. All spec changes are sent to an super set email distro indicating the updates and the location on the network share where the spec can be found.
We use Alfresco, in its Community version, from both its Share and Explorer web interfaces.
Quite useful, with a document library, wiki, forum and calendar.
We curently host about 1.8 Go consisting mainly in docs, versionned and sometimes automatically converted to PDF (by creating an automatic content rule).
FTP, WebDav and network share are also used to access to the same repository.
You could take a look at Microsoft Groove - the collaboration software that Microsoft bought a few years back.
It's bundled free with premium versions of Microsoft Office.
You can customize the workspace with discussion boards and can fairly seamlessly store collaboratively-edited Office documents.
We use MediaWiki for dos & specs. Wiki definitely wins anything like Microsoft Word or SharePoint - it allows you to develop a documentation in "first refer, then describe" = "divide and rule" way. Perfect for developers - they used to think the same way. The process of developing a documentation is almost ideal: you start from TOC and drill down until you write the document for every link you put earlier.
MediaWiki is quite customizable - there are lots of extensions there. The most necessary ones are:
Source code highlighter - CSO_Source
Our own templates integrating wiki with class reference.
Others are InterWiki, FileProtocolLinks, YouTube (we use customized version of it to display HD video), ReCaptcha, SpecialDeleteOldRevisions, Maintenance.
Some integration examples are here.
And we use Google issue tracker to track the issues. Its main advantages:
Imput usability: the process of adding\changing the issue is really convenient there. Earlier we tried Track Studio - the same actions require 2-3 times more time there, so it died fast simply because most of us hated to use it.
Customizable grids. See the examples. Really helpful.
Atom\RSS support. So everyone knows what's going on.
There is a Gurtle tool integrating it with TortoiseSVN. Really helpful.
Its main disadvantage is that it can't be closed from the public access. This makes it simply unusable in many cases.
If you want a UI similar to Word, why not use Word with SharePoint 2007? You're on 2003 so the experience is there. Upgrade to SharePoint 2007 and you can have the collaboration, Word features, document sharing, and so on.
This is the kind of thing Microsoft wants people to use Office for, so there's a ton of doco out there about how to configure your SharePoint and Office environment to support collaboration.
There is something that Google do in this direction and it looks really cool: wave.google.com. It would be a great step in collaboration and worth to wait it.
Here we use Google Docs it makes the documents available to everyone write or read only, public or private among people that have or not Google accounts, it also can import Word docs, not to mention that it runs directly into the browser so it has high availability with zero cost and zero setup, also its computer/OS agnostic, we have a nice experience with it.
Also perhaps you should take a look at Basecamp or Backpack at 37Signals, any of then might also fit your bill.
We use DocBook for all of our specifications (and other customer-facing documentation). DocBook is an XML format that lets you easily generate documents in just about any format, including PDF, which is how we distribute things to clients to get them signed off. We can divide a document into files (by section) and commit everything to our source control system (Subversion). Because it is all XML (i.e. text-based), Subversion's automatic merging and conflict resolution works great if two people work on the same file. We have a set of stylesheets that all of our documents use, so all documents share the exact same style/format, with no extra work on our part.
And if you don't like editing XML files directly, there are GUI front-ends that provide a reasonably WYSIWYG-like experience. I believe that most people in my office use XMLMind. Still, we happen to all be technical people so if we had to write XML directly it wouldn't be an issue.
As a sidenote, we also put out release notes. We have some XSLT that lets us write documents like this:
<bugs>
<bug id="1234" component="web">JavaScript error when clicking the Kick Me button</bug>
</bugs>
We then have a script that runs through our Subversion repository doing an svn log from the previous release tag to the current release tag, and some Bugzilla integration to automatically generate release notes on-the-fly.
(also, for most internal-only documentation, we use MediaWiki, which is also a great way to collaborate.)
We use OnTime. It was originally only used for defect tracking, but we've started using it to track features as well. These can be used to document the feature as it evolves during development. Features can be grouped together into sprints or releases, and time can be tracked against each feature. If you are using SCRUM, you can also plot burn-down charts for each sprint. It also has wiki functionality.