Related
I'm curious to know some more details about the various SQL standard's, i.e. SQL-92, SQL:99, SQL:2003, SQL:2008 etc. There is a short and useful overview on Wikipedia, with links to very expensive documents. Why are those documents not open to public? Can I find some open and free information?
Please, don't post links you found from Google. I'm interested in somewhat authoritative documentation only.
Quoting from one of my web sites:
We all love open source software. Wouldn’t it be great if
international standard documents such as the SQL standard would be
open too?
As a matter of fact: they are!
However, they are not free—just public. Very much like open source
software is not necessarily free. Too often, we neglect these
differences. Just because we have to pay for the standard doesn't mean
it is secret.
A download of the most relevant part of the SQL standard—part 2—is
available for USD 60 at ANSI. A CD with all parts on it can be bought
from ISO for CHF 352. Not free, but affordable.
You mentioned in some comments that you are mostly interested in part 2, so spending USD 60 might be your best option.
If you just need to know about the syntax up to 2003, there are two great free resources:
BNF grammar of SQL-92, SQL:1999 and SQL:2003: http://www.savage.net.au/SQL/
Online validator for SQL:1999: https://developer.mimer.com/services/sql-validator-99/
Finally, the complete text of “SQL-99 Complete, Really” is available at the MariaDB knowledge base. However, this book was written in 1999 when no database actually supported the described features. Keep that in mind when using this resource.
Other answers also mentioned "free" copies of the standards available on the web. Yes there are—those are mostly draft versions. I can't tell which of them are legal, so I rather not link them.
Finally a little self ad: I've just launched http://modern-sql.com/ to explain the standard in an easily accessible way to developers. Note that the actual standards text is written like laws are written :) Depending on your background, that might anyway not what you want.
The Postgresql Developer FAQ maintains links to each of them:
http://wiki.postgresql.org/wiki/Developer_FAQ#Where_can_I_get_a_copy_of_the_SQL_standards.3F
There are some hyperlinked versions of 92, 99 and 2003 here
However, I've never been able to use them effectively (read: I gave up).
This 92 text is useful (and is quoted here on SO several times)
ISO/IEC 9075-1:2011 -- google that.
Actually, digging around I found
http://www.incits.org/standards-information/
and it has freely availble section that clicks to something that redirects to here:
http://standards.iso.org/ittf/PubliclyAvailableStandards/index.html
And finally the standards.
You have to accept a license agreement to download a pdf.
However, from what I have read in my pursuit - the RDMS well the 'RD' part is going the way of the dinosaur.. If you are building something new (therefore want the new standards) you may want to reconsider all options.
You don't have to pay for all of the standards. SQL-92 is freely available, for instance.
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 2 years ago.
Improve this question
I try to be very cautious with this question. There are at least three different web-development frameworks available in Smalltalk. The most prominent seems to be Seaside but there is also AIDA/Web and Iliad.
They seem to be very similiar, but this impresson may be wrong. I wonder who has tried the different tools and can share the pros/cons of the different packages.
A more concrete question would be, do yo know of let's say any software in the bookkeeing area which has choosen to use either of the three (or other) web development frameworks.
Here's one other question. What about maturity and compatiblity. Which framework can one judge as the "most" stable?
99% of my practical experience is with Iliad, so my comparison is primarily about how I got to choose Iliad instead of the others.
Seaside. Tried it first, it is the most known and the first you stumble in. I found it hard to understand (as always, no matter what you use, when it gets to real implementation you always run into issues that fit badly with the general theory), there was little documentation around and the community seemed to care little about telling n00bs how to grow up. I eventually dropped it to check Aida. You find them here: http://seaside.st/ and on IRC at #seaside
Aida. I really liked it, as Janko is extremely patient and supportive. It is large, though. I decided to use it, when I was to start implementation for our project and it was only by chance that I ran into Iliad a few days before starting. You find Aida here: http://www.aidaweb.si/ and on IRC at #Aida
Iliad. The main reason I chose it was that I had just dropped Squeak and switched to gnu-smalltalk. gst seemed to have a lot of ongoing activity on Iliad, so I reckoned I was probably going to get a better assistance with it. It is much smaller as a concept (though it does absolutely everything) and I had very little trouble in getting started and in tweaking it to what I needed for. It also proved to be well managed, as I went thru 3 releases without ever being in trouble with what I had already deployed. You get answers to questions usually in 12-24 hours max, which is fine for me. You find Iliad here: http://www.iliadproject.org/index on IRC issues are usually channeled on the #gnu-smalltalk channel
What we are doing is a GUI for a PostgreSQL database used to manage a large multimedia dictionary, that in turn produces content (among others, for KDE-edu). I have no notion of booking apps in general, so I cannot answer to your question properly.
Yet, speaking as an analyst, a booking app is mostly a DB with an online GUI, so I see no reason why you could not make it. Much will depend on how easily your db can translate into objects. You could use a RDBMS, as we did, and design tables to map objects, or use an OODBMS. Both solutions have pluses and minuses, none of them is going to have an impact on your choice of framework, I'd say.
My suggestion is that you take a month or so in making experiments and see what better fits you. I don't think there is a tool that fits everyone, we are all different and what is easy for me may be hell for someone else (and the other way round, obviously). So try your car before buying it ;)
I would not invest too much time in studying the general theory. Using a smalltalk framework is going to turn upside down the way you make a web app anyway, and your first contact is going to be full of "false friends" you inherit from previous mindsets. Your best asset is definitely going to be "how quick can I grasp what they tell me", and this is largely an individual thing, depending on you and on who you bump into. So I'd really suggest you get your hands dirty BEFORE reading too much theoretical stuff.
These frameworks are all quite different and have different goals. It would be interesting to collaboratively create some kind of comparison.
As an author of Seaside I can provide the key properties of Seaside only:
Seaside makes building web applications feel like composing traditional GUIs: components can be freely composed and reused. Sequences of components are defined using a sequence of Smalltalk statements.
Seaside has a layered architecture, providing you with high-level abstractions (components, control flow, callbacks, HTML generation, JavaScript generation, ...) over low-level concepts (HTTP, Request, Response, URLs, HTML, JavaScript). If you need to, Seaside gives you full access to low-level constructs too.
There are two Seaside books to help you get started: Dynamic Web Development with Seaside and Seaside Tutorial.
Seaside provides a tight integration into various state of the art web technologies: JavaScript (JQuery and JQueryUI), SVG, RSS, HTML5, Comet (Server-Push)
Seaside runs identically on most today's Smalltalk platforms: Pharo Smalltalk, Squeak, GNU Smalltalk, GemStone Smalltalk, VW Smalltalk, VA Smalltalk, and Dolphin Smalltalk. It is supported by all vendors of Smalltalk platforms.
Seaside provides industry proven open-source components for meta-modeling (Magritte) and content management (Pier).
Let me introduce some strengths of Aida/Web too, because as its author it would be hard to me to compare with other two frameworks. Aida strengths are:
RESTfull URLs
MVC support, every domain object can
have its own RESTfull URL, each domain class has its own web presentation class,
Integrated AJAX and Comet
support, you don't see any difference
between a traditional and Ajax
programming anymore,
Tree-like control flow for GUI-like
control flows, without need for
continuations
Building web pages programatically by
composing from components/elements
(no template based)
Scalable in complexity and performance
Integrated security with access
control and users/groups management
Ported to most Smalltalk dialects:
Squeak/Pharo, VisualWorks, Gemstone
GLASS, Dolphin, Smalltalk/X
Prime and most fresh example of Aida at work is this year Smalltalk Google Summer of
Code site.
This is the is a nice example because it was developed it in maybe a week in
total, together with a development of GSoC process in parallel and in
the same time managing that process as an admin. This site is actually
an extended Aida/Scribo CMS, with strong use of so called scriblets,
that is, dynamic web "includes" directly into the content of the site.
That way I was able to very quickly support the new ideas which come
during the evolving GSoC process.
Well, Suixo uses Seaside. Take a look at the GSoC projects we defined. Its more ERP than bookkeeping, and currently focused on healthcare.
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 5 years ago.
Improve this question
I have always liked the documentation on Java APIs, generally speaking, but I know some people consider them lacking. So I'm wondering, what do you consider a good example of API documentation?
Please, include a link or an actual example in any answer. I want to have references that I (and others, of course) can use to improve our own documents.
A good documentation MUST have:
datatypes specs - often more essential than actual functions. Do NOT treat this lightly.
function specs (this is obvious). Including What given function does, why it does it (if not obvious), and caveats if any.
an introduction document that binds the whole into a logical entity, explaining the intentions, correct usage patterns and ideas beyond the scope of actual API code. Normally you are given 50 different functions and you don't know which must be used, which shouldn't be used outside of specific cases, which are recommended to more obscure alternatives and why must they be used that way.
examples. Sometimes they are more important than all the rest
I know how to draw an arbitrary shape of arbitrary color in GTK+. I still have no clue why a change of drawing color requires three quite long lines of very obscure, quite unintuitive lines of code. Remembering SVGAlib's setcolorRGB(r,g,b); draw(x1,y1,x2,y2); I find it really hard to comprehend what possessed the authors of GTK+ to complicate things so much. Maybe if they explained the underlying concepts instead of just documenting functions that use them, I'd understand...
Another example: yesterday I got an answer that allowed me to understand SQLite. I understood a function extracting data from a column returns signed long long. I understood the integer columns could be 1,2,4,6 and 8 bytes long. I understood I can define a column as "UNSIGNED INT8", or "TINYINT". I didn't quite get what "affinity" meant, I just knew both had "INTEGER" affinity. I spent hours seeking whether timestamps should be UNSIGNED INTEGER or INT8, whether INT8 is 8-digits or 8-bytes, and what is the name of that esoteric 6-byte int?
What I missed was that "UNSIGNED INT8", "TINYINT" and the like are all a syntactic sugar synonyms for "INTEGER" type (which is always signed long long), and the lengths given are for internal disk storage only, are adjusted automatically and transparently to fit any value on least number of bits and are totally invisible and inaccessible from the API side.
Actually the iPhone (really Mac Cocoa/framework) documentation has gotten pretty good. The features I like are:
Very easy jump to docs from the API.
Well formatted and the code snippets
you would want to copy and paste
(like method signatures) stand out.
Links to projects with sample code
right from the docs.
Automated document refresh mechanism,
but by default docs are all local to
start (so you can live with a flaky
internet connection).
Easy way to switch between variants
of documentation (to see different
versions of the OS), and also select
which sets of documentation to run
searches against.
An overview section explains what the
class is for, followed by a section
breaking out methods grouped by
purpose (methods to create and
object, methods to query for data,
methods to work with type
conversions, etc), followed by the
detailed method explanations.
I also personally really liked Javadoc and the Java system documentation (I used that for many years), I found a benefit there was it was a little easier to make your own custom docs for your own classes that flowed well with the system docs. XCode lets you also use Doxygen to generate documentation for your own classes, but it would take a but more work to format it as well as the system class docs, in part because the system framework documents have more formatting applied.
A good API will have the following characteristics:
Easy to learn
Easy to use, even without documentation
Hard to misuse
Easy to read and maintain code that uses it
Sufficiently powerful to satisfy requirements
Easy to extend
Appropriate to audience
The most common mistake I see in API design is when developers feel auto-generated XML commenting is sufficient, and then precede to auto-generate their API based off of the XML comments. Here's what I'm talking about:
///<summary>
/// Performs ObscureFunction to ObscureClass using ObscureArgument
///</summary>
void ObscureClass.ObscureFunction(ObscureArgument) { ... }
API's like the one above are only counter-productive and frustrate the developer using the API. Good API documentation should give developers hints as to how to use API and give them insight into certain facets of the API they otherwise would not notice.
I personally believe a perfect example of good documentation is PHP's documentation:
For an example:
http://www.php.net/manual/en/function.fopen.php
I think effective documentation includes:
Parameter listing
(Useful) description of the parameter
If they parameters are a string, list
out and EXPLAIN every possible
possible parameter
Return values on both successful
execution and non-successful
execution
Any exceptions/errors it can raise
Examples (THE MOST IMPORTANT imo)
Optionally:
Changelog
Notes/Examples from other users
Whenever I look up something in the PHP documentation I almost know exactly how to use it without having to scour the internet to find "better" examples. Usually the only time which I need to search the internet is when I need to find how to use a set of functions for a specific purpose. Otherwise, I think the PHP documentation is the greatest example of excellent documentation.
What is think is an example of a alright documentation is Python's:
http://docs.python.org/py3k/library/array.html
It lists out the methods but it doesn't do a good job of actually explaining in depth what it is, and how to use it. Especially when you compare it to the PHP docs.
Here is some really bad documentation: Databinder Dispatch. Dispatch is a Scala library for HTTP that abstracts away the (Java) Apache Commons HTTP library.
It uses a lot of functional-syntax magic which not everyone is going to be very clear on, but provides no clear explanation of it, nor the design decisions behind it. The Scaladocs aren't useful because it isn't a traditional Java-style library. To really understand what is going on, you basically have to read the source code and you have to read a load of blog posts with examples.
The documentation succeeds in making me feel stupid and inferior and it certainly doesn't succeed in helping me do what I need to do. The flipside is most of the documentation I see in the Ruby community - both RDoc and in FAQs/websites/etc. Don't just do the Javadoc - you need to provide more comprehensive documentation.
Answer the question: "how do I do X with Y?" You may know the answer. I don't.
My main criteria is - tell me everything I need to know and everything I'll ever want to know.
QT has pretty decent docs:
http://doc.qt.digia.com/4.5/index.html
Win32 MSDN is also pretty good although it didn't age well.
The java docs are horrible to me. They constantly tell me everything I don't want to know and nothing of what I do want to know. The .NET docs has a similar tendency although the problem there is mostly the extreme wordyness, overflow of so much superfluous details and so much god damn pages. Why can't I see both the summary and the methods of a class in the same page?
I like Twitter's documentation. To me a good API is up to date, easy to read and contains examples.
I think that a good API document needs to clearly explain:
What problem this API solves
When you should use it
When you shouldn't use it
Actual code showing "best practice" usage of the API
Not quite API documentation but nevertheless quite useful is the Oracle database documentation, e.g. for the SELECT statement. I like the inclusion of diagrams which helps to clarify the usage for example.
Just a few thoughts...
Examples - win32 API documentation is better than iPhone's because of:
(short) code examples
I vote for any API doc with small and make-sense examples
Don't ever never show "Form1", "asdf", "testing users" in screen shots or sample codes
good API is solving real world problems and there should be some meaningful examples
Don't auto-gen doc
documentation should not be done during writing code (or by the same guy)
doc is for a stranger, whom the programmers usually don't care of
Avoid ___V2 version of API
but it's not a doc issue
Basically, tell the story of the class at the class level. Why is this here? What should it do? What should be in here? Who wrote it?
Tell the story of methods at the method level. What does this do? No matter how accurate your methods names are, 20-30 characters just won't always cut it for descriptiveness.
#author:
Who wrote this? Who's proud of it? Who should be ashamed of their work?
Interface level documentation tells me:
what should this do?
what will it return?
Implementation level documentation tells me:
how does it do it? what kind of algorithm? what sort of system load?
what conditions might cause a problem? will null input cause an issue? are negative numbers okay?
Class level documentation tells me:
what goes here? what kind of methods should I expect to find?
what does this class represent?
#Deprecated tells me:
why is this planned for removal?
when is it expected to be removed?
what is the suggested replacement?
If something is final:
why didn't you want me to extend this?
If something is static:
remind me in the class level doc, at least implicitly.
In general: you're writing these for the next developer to use if and when you hit the lottery. You don't want to feel guilty about quitting and buying a yacht, so pay a bit of attention to clarity, and don't assume you're writing for yourself.
As the side benefit, when someone asks you to work with the same code two years from now and you've forgotten all about it, you're going to benefit massively from good in-code documentation.
First point for a great API-documentation is a good naming of the API itself. The names of methods and parameters should be say all. If the language in question is statically typed, use enums instead of String- or int-constants as parameters, to select between a limited set of choices. Which options are possible can now be seen in the type of the parameter.
The 'soft-part' of documentation (text, not code) should cover border-cases (what happens if I give null as parameter) and the documentation of the class should contain a usage-example.
Good documentation should have at least the following:
When an argument has additional limitations beyond its type, they need to be fully specified.
Description of the [required] state of an object before calling the method.
Description of the state of an object after calling the method.
Full description of error information provided by the method (return values, possible exceptions). Simply naming them is unacceptable.
Good example: Throws ArgumentOutOfRangeException if index is less than 0 -or- index is greater than or equal to Count.
Bad example: Returns 0 for success or one of the following E_INVALIDARG, etc... (without specifying what makes an argument invalid). This is standard "FU developer" approach taken in the PS3 SDK.
In addition, the following are useful:
Description of the state of an object if an exception is thrown by the method.
Best practices regarding classes and groups of classes (say for exceptions in .NET) in the API.
Example usage.
Based on this:
An example of great documentation is the MSDN library.
To be fair, the online version of this does suffer from difficulty of navigation in cases.
An example of terrible documentation is the PS3 SDK. Learning an API requires extensive testing of method arguments for guessing what may or may not be the actual requirements and behavior of any given method.
IMO examples are the best documentation.
I really like the Qt4 Documentation, it first confronts you only with the essential information you need to get things working, and if you want to dig deeper, it reveals all the gory details in subsections.
What I really love, is the fact that they built the whole documentation into Qt Creator, which provides context sensitive help and short examples whenever you need them.
One thing I've always wanted to see in documentation: A "rationale" paragraph for each function or class. Why is this function there? What was it built for? What does it provide that cannot be achieved in any other way? If the answer is "nothing" (and surprisingly frequently it is), what is it a shorthand for, and why is that thing important enough to have its own function?
This paragraph should be easy to write - if it's not, it's probably a sign of a dubious interface.
I have recently come across this documentation (Lift JSON's library), which seems to be a good example of what many people have asked for: nice overview, good example, use cases, intent, etc.
i like my documentation to have a brief overview at the top, with fully featured examples below, and discussions under these! I'm surprised that few include simple function arguments with their required variable types and default values, especially in php!
I'm afraid i can't really give an example because i havent trawled through to find which ones my favourite, however i know this probably doesn't count because its unofficial but Kohana 3.0's Unofficial Wiki By Kerkness is just brilliant! and the Kohana 2.34 documentation is pretty well laid out too, well at least for me. What do you guys think?
Most people have listed the points making up good API documentation, so I am not going to repeat those (data type specs, examples, etc.). I'm just going to provide an example which I think illustrates how it should be done:
Unity Application Block (Go to the Download section for the CHM)
All the people involved in this project have done a great job of documenting it and how it should be used. Apart from the API reference and detailed method description, there are a lot of articles and samples which give you the big picture, the why and how. The projects with such good documentation are rare, at least the ones I use and know about.
The only criteria for documentation quality is that it speeds up development. If you need to know how something works, you go and read docs. One doc is better than another if you've understood everything from first doc faster than from from second.
Any other qualities are subjective. Styles, cross-references, descriptions… I know people who likes to read books. Book-styled doc (with contents/index/etc.) will be good for him. Another my friend likes to doc everything inside code. When he downloads new library, he gets sources and "reads" them instead of docs.
I, personally, like JavaDocs. Like Apple dev docs with the exception of lower-level parts, for example, Obj-C runtime (reference part) is described awfully. Several website APIs have docs I like also.
Don't like MSDN (it's good in general but there are too many variants of the same document, I get lost often).
Documentation is only a part of the big picture, API design. And one could argue the latter is much more important than just the naming. Think of meaningful non-duplicating method names, etc.
I would definitely recommend watching Josh Bloch's presentation about this:
http://www.infoq.com/presentations/effective-api-design OR http://www.youtube.com/watch?v=aAb7hSCtvGw
This covers not only what you're looking for but much more.
Lots of practical, real-world examples are a must. The recent rewrite of jQuery's API documentation is a good example, as well as Django's legendary docs.
The best documentation I've found is Python. You can use sphinx to generate the source documentation into HTML, LaTeX and others, and also generate docs from source files; the API doc you are looking for.
API docs is not only the quality of the final documentation, but also how easy is for the developers and/or technical writers to actually write it, so pick a tool that make the work easier.
Most things about good documentation have already been mentioned, but I think there is one aspect about the JavaDoc way of API documentation that is lacking: making it easy to distinguish between the usage scenarios of all the different classes and interfaces, especially distinguishing between classes that should be used by a library client and those that should not.
Often, JavaDoc is pretty much all you get and usually there is no package documentation page. One is then confronted with a list of hundreds or even more of classes: where and how to start? What are typical ways of using the library?
It would be good if there were conventions of how to make it easy to provide this information as part of JavaDoc. Then the generated API documentation could allow for different views for different groups of people -- at a minimum two groups: those who implement the library and those who use it.
I find Google APIs a beautiful example of Good documentation API.
They have:
Bird's eyes view of the entire APIs structure
Overviews of the main features of the single API
Nice and colored examples for a quick feedback
Detailed references
A blog that keep you updated
A google groups that documents problems and solutions
Videos
FAQ
Articles
Presentations
Code Playground
A search engine to crawl inside a pile of documentation
That's it!
When I play with google APIs documentation site, I feel at home.
Go to the Doxygen site and look at the examples of the HTML that it generates. Those are good:
http://www.doxygen.nl/results.html
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 11 years ago.
An obvious answer is "an internal wiki". What are the pros and cons of a wiki used for software documentation? Any other suggestions? What are you using for your software documentation?
Loren Segal - Unfortunately we don't have support for any doc tool to compile information from the source code comments but I agree it would be the best way to store technical documentation. My question was about every kind of documentation tho - from sysadmin type to user documentation.
That's a very open ended question, and depends on many factors.
Generally speaking, if you use a language that has good documentation generation tools (javadoc, doxygen, MS's C# stuff), you should write your documentation above your methods and have your tools generate the pages. The advantage is that you keep the source of your text alongside your code which means it is orgnanized in the logically correct place and easily editable when you make a change to the behaviour of the method.
If you don't have good doc tool support or don't have access to source code, wiki's aren't a bad idea, but they're a second choice to the above.
Note: I'm talking only about code documentation here. Other artifacts obviously cannot be stored alongside code-- a wiki is a great place to put those documents. Alternatively if you use some CMS you can simply commit them in some docs/ folder as text/pdf/whatever files to be editable via the repository. The advantage there is that they stay with the repository if it is moved whereas a wiki does not (necessarily).
Tools are important, but don't get too bogged down in finding the magic tool. No tool I've found yet has a "document everything magically using tiny invisible elves" tickbox. :-)
A wiki will work fine. Or Sharepoint. Or Google docs. Or you could use a SVN repository. Hell you could do it with pens, notepaper, and a file cabinets if you really really had to. (I really don't recommend that!)
The big important key is you need to have buy-in throughout the organization. What happens in a lot of shops is they go and spend a bunch of time and money on some fancy solution like Sharepoint, and then everyone uses it religiously for about two weeks, and then people get busy with hitting the latest milestone and that's the last anyone hears about it.
Depending on your organization, field, the type of products your developing, etc., there are a few solutions to that, but one way or another you need to set up a system and use it. Appoint someone the official documentation czar, give them a cluebat, and tell them to hit people in the head everytime they say "oh yeah, I'll finish documenting that next week...". if that's what it takes. :-)
As for tools... I'd recommend Confluence by Atlassian. It's a fine wiki, it's designed to work in an enterprise environment, it has a lot of nifty features, it's customizable, it integrates well with some of the Atlassian's other nifty tools, and is basically a pretty solid product.
«Software documentation» is a very general term. There is «End User documentation», «Developer documentation», «QA Documentation». First one is usually developed by qualified techwriters. Other ones may be dynamically formed from wikis, documentation comments from source code etc. All this stuff maintenance process usually is very complex and each software company follow its own way. But there is one necessary point for all these ways: each code commiter, architect, manager, qa engineer MUST store well arranged each piece of information which may be helpful for the others. And someone else MUST keep an eye on this pieces storage and rearrange pieces if required. All this steps greatly improve all activities related to development process.
Assuming you are talking about code documentation versus user documentation, an internal wiki is great if you do not need to distribute the documentation for the code outside of your organization, to contractors or partners.
Javadoc or DOxygen is more suitable if you want distributable code documentation.
If you are referring to user documentation, you may want to have a look at DITA.
I started experimenting with a way to do user documentation with these goals:
Markdown/Html/Javascript/file-based relatively linked documents for portability (can run on local file system or you can throw it on a webserver), built-in handling of screenshots (interactively resize), and open source in case anyone else may want to do something with the crazy thing.
Your document source is written in Markdown and rendered to Html via Javascript at browser runtime.
Mandown - http://wittman.org/mandown/
We currently use inline documentation parsed by an external application (PHP + PhpDocumenter) plus various internal wikis. At times it's painful at best (mainly because only one person update the wikis or the docs...)
However, I've been looking at using ikiwiki to do internal docs. It integrate with your source countrol system (including Git, Subversion, Mercurial, Bazaar, TLA and Monotone) so all your docs track with your project. It is built in Perl and has an extensive plugin system (including multiple markup languages, with the default being Markdown). Also, the source control system is plugin based, so if what you use isn't immediately supported you could add your own. In your preferred language, if need be, since it supports non-perl plugins, too.
My company uses a variety of Sharepoint and a wiki. Sharepoint for specific documents like requirements, presentations, contracts, etc, while the wiki is used as a help guide a developer repository for tutorials on using internally developed libraries.
Yeah, we use a wiki, we also use Google documents. I find that Google documents is better than most wikis I've tried and, if you don't need to track all changes, you lose nothing. Google docs provides a good collaboration framework.
we're developing a web app to cover all aspects of a printing company from finances, to payroll, to job costing. Its important to be able to control who can access what parts of these applications. Don't want a line employee giving himself a raise, etc...
I've heard of the concept of ACL & ACO, but haven't found a good example that we could adapt to our project.
Anyone know where I can find good information to work from?
A brief rundown on ACLs, where they should be used and how they should be structured and implemented for various applications and user levels can be found here:
LINK
I've had to implement that type of security a couple of times. Unfortunately I don't know of any really good articles that provide examples. My implementations were mainly piecing together the parts through trial and error.
However, I did come across this link on MSDN:
http://msdn.microsoft.com/en-us/library/52kd59t0(VS.71).aspx
It has some of the concepts.
After my original post, I did some more research. I found this article:
http://www.aspfree.com/c/a/C-Sharp/Implementing-Role-Based-Security-using-CSharp/
it seems pretty promising, I didn't go through all the details, but it at least guides you through the high-level topics.
If you're using .NET/Windows you might want to look into Windows Authorization Manager (AzMan). There are support for AzMan in Enterprise Library but there are other ways of using it as well.
http://msdn.microsoft.com/en-us/library/ms998336.aspx
http://alt.pluralsight.com/wiki/default.aspx/Keith.GuideBook/WhatIsAuthorizationManager.html