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 4 years ago.
Improve this question
I regularly get frustrated by text-overload in my IDE (Eclipse right now). I find myself separating my methods by big chunks of whitespace, and then regretting that later when I need to find something by scanning through the code.
Something I think does work well is the GrepCode way of viewing source code. Does anyone know if anything like this has been implemented in a code editor? More specifically, I want the ability to have nice, formatted and colourful documentation (preferably collapsable) to help me read my code. It could even have the ability to embed design images.
"Text-overload" is precisely why a plugin like Mylyn does exist.
Mylyn's task-focused interface reduces information overload and makes multitasking easy.
Mylyn makes tasks a first class part of the IDE, integrates rich and offline editing for ALM tools, and monitors your programming activity to create a "task context" that focuses your workspace and automatically links all relevant artifacts to the task-at-hand.
This puts the information you need at your fingertips and improves productivity by reducing information overload, facilitating multitasking and easing the sharing of expertise.
Plus you can add to your project WikiText, with Markdown support (see WikiText FAQ, and its User Guide)
To better manage huge amounts of code, you may want to reconsider these:
Use Eclipse Mylyn, as it will hide code that you don't work with.
Open Windows -> Preferences, type "Folding" in the preferences dialog
and check, which editors should provide more folding by default to
hide non relevant things from you.
Have a look at the Java browsing
perspective of Eclipse. It stems from the old Smalltalk code browsing
user interfaces and is meant to more easily manage (but not edit)
Java code.
If you are working much visually with your code (and remember its layout instead of the structure), you may find the Crazy Outline view very helpful. It provides an airplane layout view of your text.
If the more important aspect of your question is how to more easily see the documentation you wrote for your code, check this:
Make sure that the JavaDoc view and the Declaraction view are opened and visible all the time to show Javadoc and declaration of whatever your cursor points at. Make sure you actually provide JavaDoc comments, to begin with.
The Eclipse Code Recommenders project has advanced documentation views, which basically show the results of data mining of common Eclipse code. You can get a company internal (commercial) version of that tool, so it would recommend code completion, as other code in your projects was written.
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 8 years ago.
Improve this question
I like F# but sometimes I need something light and cross-platform and without .NET for sure.
I tried to use OCamL many times but seems like I just can't start it.
Installed IDEA, added OCamL plugin -> Doesn't work
Installed eclipse ODT plugin -> Can't launch even config OCamL compiler - too complicated
Even had tried NetBeans plugin a long time ago but even can't deal with it.
So, for now, I'm using ocamlc -o "main.exe" "main.ml" from the command shell and different light editors. I don't use Vim or Emacs, I'm using nano and I have a habit of usage full-featured IDEs.
I found various documentation (this is looking like the best to start http://caml.inria.fr/pub/docs/oreilly-book/html/index.html for me) but still being confusing when looking for something a bit specific alike sqlite access. found this: http://neugierig.org/software/ocaml/sqlite/ with strange api annotation and no examples. And all the documentation about IDE usage I found are outdated or doesn't work.
Addition subquestion: some people told me "don't use OCamL, it's a dead language for students with low libraries support and seems like dying, use python or ruby instead". But I like the beauty of OCamL. I want to give it a try. Tell me if that is normal to use OCamL for production code today?
thank you.
There is TypeRex, a new development environment for OCaml. Here is a summary of TypeRex features:
Improved syntax coloring
Auto-completion of identifiers (experimental)
Browsing of identifiers: show type and comment, go to definition, cycle between alternate definitions, and semantic grep;
Strictly semantic-preserving, local and whole-program refactoring:
renaming identifiers and compilation units
open elimination and reference simplification
Robust w.r.t. not-recompiled, possibly unsaved buffers
Scalable (used regularly on a few hundreds of source files)
There are some screenshots available on the website. The first release candidate is out since yesterday.
EDIT: The first release (v1.0) is out now :-)
There are a few options:
Tuareg for emacs was already mentioned: http://tuareg.forge.ocamlcore.org/
vim has a few options for OCaml integration, with one good example available here: http://www.ocaml.info/software.html#vim
OcaIDE seems to be the best option for Eclipse: http://www.algo-prog.info/ocaide/
Geany, Komodo Edit and a number of other editors have syntax highlighting support for OCaml and some extra IDE-like features which are independent of the programming language being used. Most of these have limited OCaml-specific support.
OCaml is not dead. Some of the more vocal industry users of OCaml are XenSource/Citrix and Jane St. Capital. The language does not receive the same public and community evangelism that some other languages receive.
It's been years, but I really liked emacs' tuareg mode http://tuareg.forge.ocamlcore.org/
But if you're afraid of emacs, then it's not the right tool.
I specially like the shell integration and the possibility to "throw" a function you're developping in the shell and then test it.
EDIT For the subquestion, OCaml seems dead, and it's a pitty. However you cannot compare it with ruby/python. I'd say it's main competitor is Haskell which seems to be growing in popularity.
Googling "ocaml ide" shows now http://camelia.sourceforge.net/ as the first result. Haven't tested it though, so I can't really say if it is recommendable or not.
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 7 years ago.
Improve this question
I am writing this very basic J2SE application which alerts the user with some info every now and then. Currently I am using the SystemTray and TrayIcon classes to show notifications, but I am not really pleased with that. It does not allow me to tweak the notifications, nor gives them a good look.
So, does anyone know an easy to use library to generate nice notifications?
btw, I will be porting to Linux (Ubuntu) to, but will be using notify-OSD there, which is exactly what I need.
Shameless plug: I've just released a project called Twinkle that is pretty much Growl for Java Swing.
I' not aware of a Java library abstracting all OS specific desktop notifications. But if you know, you are limited to Ubuntu (and perhaps a limited number of other OS), you can create a own Interface and implement it for the specific OS.
Ubuntu: You can access /usr/bin/notify-send via Runtime like this: usr/bin/notify-send -t 30000 "Text1" "Text2" -i /path/to/48x48.png
Mac OSX: Java Growl API
For JAVA implementations you may look at Jazz or Mylyn (see Java Desktop Notifications).
You can use JCommunique for cross-platform Java desktop notifications. Here is a short demo adapted from the examples on the wiki:
// makes a factory with the built-in clean theme
// themes are customizeable
NotificationFactory factory = new NotificationFactory(ThemePackagePresets.cleanLight());
// factories build notifications using a theme, while managers handle how
// how they appear on the screen
// this manager just simple pops up the notification in the specified location
// other managers do sliding, queues, etc.
NotificationManager plain = new SimpleManager(Location.NORTHEAST);
// creates a text notification; you can also have progress bar Notifications,
// icon Notifications, Notifications that ask for user feedback, etc.
TextNotification notification = factory.buildTextNotification("This is a title",
"This is a subtitle");
notification.setCloseOnClick(true);
// the notification will disappear after 2 seconds, or after you click it
plain.addNotification(notification, Time.seconds(2));
Brief confession: I also am the creator of this project. It's open source so I don't get any revenue from it.
Some other libraries to have a look at:
Twinkle
This is already mentioned in another answer so I won't say too much about it. I tried the Java Webstart demo and it looked pretty nice. It allows for some more complicated background color options such as gradients that JCommunique doesn't have.
About 3,500 lines.
Has a bunch of fancy styling options such as round vs. rectangle close buttons, gradient vs. solid color, and light vs. dark notifications. However, has just one sequential manager.
The wiki has links to javadocs and a getting started document.
No external dependencies (I think?).
JCarrierPigeon
Very lightweight. Looking at the jar, it has just six classes.
Depends on the "Timing Framework" library.
The website shows that it can do some sliding in effects, but I don't think it does fading or other types of animations.
JTelegraph
Requires JCarrierPigeon and "Timing Framework" in the classpath to build
Has dozens of nice-looking icons included with the project. I'm not sure how these are licensed, but they could be useful if you don't have your own.
As far as I can tell, it doesn't include many more features than those provided in JCarrierPigeon. It mainly includes a bunch of built in icons and a different API.
I can't post links to these since I don't have enough reputation, but they are easy to find on the internet.
Now I will try to objectively evaluate my own library in comparison with the above. Please keep in mind that this list is a bit more extensive since I know more about my project than the others. Let me know if there is anything that I'm missing.
JCommunique
Many features. As far as Notifications go, there are TextNotifications, IconNotifications, AcceptNotifications, and ProgressNotifications (show a progress bar). NotificationManagers handle how Notifications show. These include SimpleManager, QueueManager (scrolls down old Notifications to reveal new ones), SlideManager (slides Notifications into position), and SequenceManager (only shows a Notification when the previous one has disappeared).
Relatively large. I think it clocks in at about 2,500 lines in total.
Has a wiki with a number of examples.
Notifications look a bit plain because they can only be one solid color. Twinkle wins in this respect; it has gradients and outlines around its notifications.
A handful of built-in themes. At time of writing these include dark, light, and aqua. You can also add your own.
No external dependencies other than Java.
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 am looking into using a wiki (prefer mediawiki, but not a req.) as the repository for developer generated documentation (User Guides, Release Notes, Application Notes, Errata, etc.) from a collaborative/easy-to-update point of view a wiki seems like a good match, however since this documentation will ultimately ship to customers we want to be able to export the documents in their final state (e.g. during the release cycle) to static versions that no longer include histories.
Ideally the export would leave the document in a form (i.e. word doc, or legible HTML) where updates could be easily made by a non-programmer.
It would be good if niceties like section ordering and table of contents were available, or easy to add after the fact.
Are any tools with features like these available?
It sounds like you need a step in your dev cycle that will take your HTML wiki contents and "documentify" them - doc/pdf/html for simpler delivery. If that's right, you could try something like Docmosis or JODConverter which can act as engines to do the conversion. The last step would be working out how to integrate it and have it automatically extract your wiki content to transform into a document.
I'm a little confused.
If you want to ship the documentation in a formal like HTML, how would users continue editing? (use DumpHTML to generate HTML).
If you want to ship the documentation in Wiki form and allow users to continue editing, why not just replicate the database and get rid of the change history until a certain point? AFAIK MediaWiki has some support for this.
One option would be Mylyn WikiText, which is used by some Eclipse projects to generate Eclipse documentation from the Eclipse wiki (which is based on mediawiki). WikiText also supports other wiki markup (trac, textile, etc.) and other output formats (docbook, HTML, etc.).
In MoinMoin Wiki you can export to DocBook. DocBook can be converted to professional looking PDFs.
DokuWiki uses plain text files as storage backend which can be simply copied to your project as documentation.
First, don't discount that MediaWiki has a permanent link function. So, if you allow the readers to access your wiki, you can just send them a URL to a specific version of the page.
Alternatives - you can print a PDF. Wikipedia uses the Collection extension but there are others.
Finally, if you use Firefox and want a client side solution, use PrintPDF
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
Currently the documentation where I work is in a bit of a state. There isn't anywhere near enough of it, and the documentation that does exist is spread out over many word documents making it hard to find anything.
I'm trying to take some initiative and get it improved, and I figure the first thing is to find a better format to write the documentation in:
My thoughts are that the documentation should be structured in a series of short articles (MSDN / Html Help style) and structured in a suitable tree:
It would be good to be able to produce a standalone Html-Help style package to be shipped with the application
As well as being able to produce a MSDN-style website as a reference for those who are too lazy to look at the CD.
Search is of course a must-have
It needs to be at least reasonably easy to update - if there is a 17 step process to update the published documentation then it makes it seem like too much work to do simple changes, and nobody can ever be bothered to update it.
The documentation is technical in nature, and so ideally it would be nice to be able to include generated documentation from things like the Xml documentation embedded in C# code. This is however definitely a side-requirement - currently very little useful Xml documentation exists, its just that in the future I plan to fix that.
For the same reason it is often good to be able to handle things like attachments (code samples etc...) I'm not expecting anything fancy, but this is something I need to bear in mind to make sure that its at least not handled badly.
Are there any projects or languages that are suited to this sort of documentation?
I've had good results with doxygen on my C and C++ projects although it supports many other languages as well. You put the documentation in comments in the code that can be simple or complex HTML markup. It is very easy to update as it is part of the code. You can make building the documents part of your build process. Additional topic that are not strictly API related can be added as separate HTML documents. The version I'm using doesn't support search so you would have to add another product to search these pages. Because it is HTML you can add in code samples, diagrams, etc.
If you use LaTeX you can get all your documentation in great looking PDFs and printed copies, as well as being able to generate html (via latex2html). TeX has the advantage of being all plaintext, too, so you can track/merge it reliably with your favourite revision control system.
We use confluence as our documentation repository. It is fairly easy to have public and private sections, and has a nice WYSIWYG editor. It can handle attachments and can be saved off as PDF documents if you like.
I've used robohelp with good results. it is plain html, but has a generation process that keeps everthing looking consistent. It can be packaged as a .hlp file with the app, or published to the website. Check it out, it is simple so you can get back to doing your job :)
A clean way is to use DocBook. It is easy write and undetstand. It is also easy to parse as XML parsers are standard and other forms of documentation (e.g. from the embedded documentation in comments) can be easily be transformed to this format.
It is straightforward to generate PDF, HTML og other formats from the DocBook source (tools exist for this purpose).
I've started using DokuWiki. Its not exactly what I was originally looking for (I think I was really looking for a CMS), but it does the job and some respects its better than what I originally had in mind (in particular its a wiki - I've not yet gotten as far as publishing this to our customers however so I'm not sure how well thats going to work out)
I'm using the IndexMenu plugin and the Arctic template to get a navigation tree on the left, and if I publish the wiki itself I'll use the discussion plugin to allow users to post feedback.
Currently my method of handling generated content is to use xslt templates to produce dokuwiki syntax, and write that output directrly to files / folders in the "data/pages" folder.
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
We would like to prepare the software usage documentation for a web application. This mainly contains the screen shots ( along with relevant documentation ) in most of the pages. Also we would like to have a top menu links using which we can jump to the corresponding pages.
Please suggest the tools which can be useful to fulfil the above requirements.
Dr Explain is pretty nice.
http://www.drexplain.com/
It will analyze your page and create a list of controls, buttons, etc. that need callouts.
If you write your documentation with a particular documentation tool in mind, outputting to HTML is relatively simple. LaTex, markdown (with Pandoc in mind), reStructuredText (with Pandoc or Sphinx in mind), AsciiDoc (with DocBook tools in mind) and DocBook (with Docbook tools in mind--see Pandoc).
All of those formats would allow you to easily organize your documentation then export them into HTML however you deem appropriate (probably by major heading, then build a simplistic wrapper around the files). Sphinx can also just output web-based documentation (see Python.org's documentation).
For screenshots I suggest using a standalone app on your platform of choice, Ideally one that lets you do annotation within the program. Skitch for Mac, Jing for Windows, Shutter shutter-project.org or Jing in linux.
Finally I would suggest also doing screencasts as they can be especially helpful to show off the interestingness/power of a web-app.
This may be overkill for your project, but I've favored preparing documentation in docbook (xml), since it's fantastically portable/convertable.
To simplify the document creation, you could turn to http://www.oxygenxml.com/, but you can also do the same work in just about any other xml (or even text) editor.
Once your document is prepared, it's trivial to generate html (multi-page, or single page), and pdf versions.
I don't know what king of language you are writing your code, but in the case of Java, you can use Maven.
With maven you can use many plugins, like JavaDoc, site that create a site with many informations about your API/software and contains the top menu that you want.
This is a screenshot of the site that maven generates: link
I hope these could help!
Cheers
I'm sure there's some awesome tool out there that integrates everything needed for usage documentation but I'll tell you what I use!
I use wink to grab screenshots of the application in use. I tend to fire it up and just grab loads of screenshots as I walk through the application, or even just a part of the application. Next, I edit the project in wink to remove redundant screen captures, re-order them and position the mouse on each frame. I then add highlighting which is usually just a nice box around the part of the screen I am demonstrating. Wink allows you to overlay the images with informational boxes and arrows, I then export the project as html and use the numbered, exported png images as the base for my documentation.
I tend to drag them into OpenOffice Writer (or whatever you are using for typesetting) and supplement them with more information - ie a few paragraphs top explain what the user is doing and why.
We use acrobat to output this documentation and providing your table of contents is done properly, it can insert bookmarks in the pdf to enable jumping to relevant sections.
The main benefit we get from wink is that it is very easy to re-grab shots when things change and it can output to flash to provide nice, snazzy demos of small pieces of functionality for posting on the web.