After googling for longer than I care to admit (maybe I'm just using the wrong search terms) it seems there doesn't exist a repository of sample EDI files anywhere. For such a pervasive data exchange format, I'm surprised. Even though there may be variations from company to company, I would still think the industry would benefit from having a repository like this.
Am I embarrassingly missing something?
You hit the nail on the head: "there may be variations from company to company". You didn't specify standard. If you're looking for EDIFACT, you're in luck! They are published freely. If you're looking for ANSI X12, well that standard library is published, but it'll cost ya. Your partners can usually send you sample files as part of the implementation. X12 handles a lot of vertical industries. Some subgroups might publish their own X12 specification (HDA for the pharmaceutical industry for the ASN, as an example).
Companies bastardize the standard all the time to suit their needs.
Feel free to download and check out this tool: https://www.liaison.com/products/integrate/edi-notepad/edi-dictionary-viewer/
I'm looking for good report library for Visual FoxPro, but it seems that there is lot "old" solutions with bad documentation. Does anyone have experience with some VFP report library?
"old" solutions? Isn't it natural that a language whose last version was released on 2007 and even the latest hotfix release was in 2009 have solutions as "old"? What is old? 1,2, 10, or 20 years? Probably the VFP9's own reporting system, and the documentation written by Cathy Pountney is considered good by many including me.
There are other reporting solutions some of which are free and some of which are not. For example you might check out Report Sculptor (free) from my friend Djordjevic Srdjan. Or you might check out another from one of my other friend Rich Simpson Mind's Eye reporting engine (paid). I have been using Mind's eye for years and I found its documentation well. Report Sculptor too is documented enough IMHO.
Old/new, good/bad are relative terms and be different from person to person. With your measures, either you didn't see the default reporting tool and Cathy's doucmentation, and those two engines yet or your 'good' expectation is much above mine.
In our company we are using Eqeus report library. We had really great experience with them. They have good documentation and their customer support always helped us. I think that free solutions cannot beat commercial use for this purpose.
I can recommend www.eqeus.com for generating foxpro reports. They have also cloud report viewer and management.
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 work at a company that, for some reason, insists that all our development documentation should be in MS Word format. Which, being a binary format, means we cannot:
Diff versions of a document against each other (so peer reviewing them is a pain - because of the domain we work in, peer reviews for all changes are essential)
Grep a folder-full of documents for keywords
What do you use to write documentation in and why?
Please also give me ammo to change this situation with...
I recently started using DocBook XML to author my documentation.
On the upside, it's a pure text format. You can break a large document into multiple files, and use nodes to bring them all together into a single book. Table of contents and index are automatically generated. Intra-document links (within arbitrary text, pointing to chapters or sections) are very easy. And with a push of a button, I can create a single-html-file version, a chunked-html version (one file per chapter), and a PDF version.
After some tweaking and customization, I'm very happy with the output. The documents look great!!
DocBook is used extensively by real publishers (most notably, O'Reilly), and it's been around for more than fifteen years, so it's reached a certain level of maturity.
On the other hand, all of the processing is done with XSLT, using an ad-hoc collection of tools. (My own docbook pipeline includes Python, Java, Xerces, Xalan, Apache FOP, and PDF-SAM. Plus the official XSLT stylesheet distribution, and my own XSLT customizations.)
DocBook is not a turnkey solution. You won't be able to get going quickly, without reading the manual. And if you don't know anything about XSLT, you'll have to learn.
On the other hand, there are only a dozen or two XML tags that you really need to know to write the documents. (The real expertise comes into play during doc generation from the XML sources.) If one person on your team was willing to be responsible for writing the doc build script, then everyone else on the team could just learn the DTD and do a decent job contributing.
Anyhow... DocBook definitely has some faults. It's not the easiest system for tech authorship. But it's the best open source tool I know of.
The "Subversion Book" is written in DocBook. Here's a page with links to the different book versions (single-html, chunked-html, and PDF):
http://svnbook.red-bean.com/
And here's a link to the DocBook XML sources for the first chapter, so that you can get an idea for how it works:
http://sourceforge.net/p/svnbook/source/HEAD/tree/branches/1.7/en/book/ch01-fundamental-concepts.xml
For ammo, there's the trusty old Pragmatic Programmer, chapter 14: The Power of Plain Text.
As Pragmatic Programmers, our base
material isn't wood or iron, it's
knowledge. We gather requirements as
knowledge, and then express that
knowledge in our designs,
implementations, tests, and documents.
And we believe the best format for
storing knowledge persistently is
plain text. With plain text, we give
ourselves the ability to manipulate
knowledge, both manually and
programmatically, using virtually
every tool at our disposal.
We use a wiki (specifically the one provided by Trac) for the two reasons you mentioned. Plus, if we really need to we can get the text version of the markup and manipulate it in a text-only environment, too (e.g. as part of svn comments during commit).
A format that can be easily reduced to text-only (non-binary) is definitely a must. Having the ability to upconvert it to a pretty format like a PDF is, for us, not terribly important.
Word has change tracking for documents (although it only works up until you accept the changes) and you can also grep them (the text isn't encrypted). So I'm not sure either of your arguments will hold up under scrutiny. I'd love to give you the ammo to change this but I've become jaded and cynical with age.
We use MS Word for our docs (which is a huge improvement over the earlier choice (Lotus WordPro - ugh!).
We use a wiki - specifically Confluence by Atlassian.
It's a commercial product, and it's great. One of the reasons we picked it over free/open wiki engines is that it has a full-blown WYSIWYG editor and various other features that make it more easily accessible to users who are familiar with Word.
We've also come up with a neat trick where we store images, designs, wireframes, etc. in Subversion, and then embed links in the wiki documents to those resources URLs via the Apache/SVN web interface module; notes on how we do this are here if you're interested.
Like Dylan's organisation, we also use the excellent Confluence wiki. I wrote an article about why this is better approach called Wiki is my word-processor, which should give you some reasons to change the situation.
Benefits of using a wiki for internal documentation include the following.
Word-processor users get sucked into changing the layout and typography, however good your templates are, which wastes time and reduces consistency.
A wiki provides full-text search, which you are unlikely to have for your body of the MS Word documents written by everyone.
A wiki provides a document version history; I have never heard of a team successfully keeping all revisions in Word documents and always being able to compare old versions, or using a version control system (with the possible exception of SharePoint but that's whole different failure scenario).
A wiki makes hyperlinks between documents easy; it is too hard to reliably link between documents in a collection of Word documents, so new documents end up duplicating older content into new monolithic documents which means they take more time to read and write.
Separate wiki pages can be edited by different people at the same time, and Confluence can merge changes when multiple people edit the same page at the same time; collaboration is harder with a Word document that only one person can edit at a time.
A wiki like Confluence automatically generates navigation pages based on wiki structure and tags; you need a librarian and lots of discipline to make it possible to browse a large collection of Word documents.
A wiki page usually loads and displays more quickly than a Word document.
A wiki page has more automatic meta-data; you need templates and discipline to make sure that Word documents always have Title, Author and Version set in the document properties and visible in the document on-screen and in print.
If you want more ammunition than this, then there is lots of wiki-promotion on The Atlassian Blog.
You could ask for documentation to be in OOXML (.docx, in the case of Word) format. Not as ideal as using ODT, in my opinion, however, it's still just a zip file with a bunch of XML files inside. :-)
A textual format facilitates merging your documentation with generated items such as JavaDoc, API references or data dictionaries. It also scales much better than word, which is hard to use for large documents. Finally, a format that allows includes allows multiple authors to work on a document concurrently.
LaTeX and FrameMaker (the two systems I have used for this) both have vastly superior indexing and cross-referencing capabilities and have either a native textual format or a textual version of their native format that can be included (MIF in the case of Framemaker). They are also both much more stable than word.
I've built tools that read data dictionaries and generate documentation that can be included into a larger document with stable indexing and two-way cross-referencing. The functional specification for This product was done with LaTeX in this way and got me another gig with the company. I have also developed a similar process with FrameMaker.
Is the entire development team against this requirement, or is it a small group? If it's the entire team, just ignore the mandate and use a text-based format -- wouldn't be the first time employees ignored a silly rule. Works especially well if you've not made a big fuss about it in the past. If you have, management might look especially hard at your docs.
MS Word supports document changes tracking and peer review.
The new MS Office format is fully XML based (to see this, rename a MS Word .docx file to a .zip, then unpack it to see).
Maybe Office 2007 may fit both your company requirements and your concerns ?
You can at least compare Word documents, see the "Track changes" command in the "Extra" menu, or use software like DeltaView. Found via google search first link at lifehacker.com. Searching in word documents should be possible with Google Desktop Search or other similar programs that index all files they are able to read.
Do they insist that you write it in Word or only that it's available in Word format? You could write in a text format and convert it to Word automatically.
Don't you store documentation files in some kind of Version Control System, ideally together with the source code? I would recommend to do this (makes it easy to get the documentation for old software releases).
And if you do store the docs in VCS, you will notice that plain text or XML-bases files are much better for this, because you can get diffs; also, changes between text files are usually stored more efficiently than changes between binary files.
Not to defend MS products here, but MS word can diff documents.
If you use Beyond Compare as the diff tool for your source-control system (As we do, with Perforce), it will show you differences between revisions of your Word docs. Admittedly, it only shows the textual differences - formatting changes are not shown - but this is usually enough for you to see what changed.
This is just another reason to invest in Beyond Compare, as it is one of the most polished pieces of software I've ever used - and it's the best $30 dollars (Less if you buy several) I've spent on software
There are many tools for word document comparison. I currently use a python script that puts a command-line on the built-in compare and merge functionality of word.
http://nicolas.lehuen.com/index.php/post/2005/06/30/60-comparing-microsoft-word-documents-stored-in-a-subversion-repository
It should be easy to automate word to extract all text from a word document into a text file. So you could write a script creating text files from word docs, and grep, compare, version control, Review these text files.
Of course this is not an ideal solution, since you loose your pretty formatting, but it should work.
I think there are programmes that convert Word docs to plain text. Use one of them to convert the word doc to plain text and then use diff, grep etc
Also have a look into recommended toolchain(s) for DocBook.
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.