Hot answers tagged documentation-generation
18
How about a logical semantically correct naming system that avoids duplication, tautology and abbrevations?
That and a Glossary and a logical / physical ER diagram of the database, preferably hosted on a Wiki of some sort, is about all you can do.
Plus what Jason Holland says in the comment below! :-)
17
I feel your pain. I've been in this exact position before.
My suggestion is to lead by example. Start a wiki or document and start making notes. Make repeated references to this document you're putting together. If someone asks you a question, make a show of looking at the document for the answer first. If the question isn't there, add it to the ...
17
I have seen it. Didn't end up well.
I think that cucumber is cumbersome (<--lol :D) abstraction for this exact reason. Too hard for non-technical people to write by themselves; too verbose for technical people.
Non technical people just haven't learned to think like programmers. It is our privilege to understand abstract knowledge, break it down, ...
9
As far as I'm concerned, the closer you keep documentation to the code, the more likely it is to be kept up to date and the more useful it is likely to be.
That's why I try to keep all documentation in the same repository as the code, even user manuals, and try to keep it in a plain text format that can be easily managed by a revision control system.
...
9
These kinds of shops are horrible to work for. I pity them as I would a wounded animal that is dying.
Old technology, overflowing with technical debt, constantly putting out fires, an ever increasingly disatisfied, angry and sometimes vendor-locked customer base... sound familiar?
You know that slight smile that you get from the overstressed manager that ...
8
I would use @deprecated for purely practical reasons.
Although @deprecated does not convey the exact meaning that you would like, it has a significant advantage: Java compiler has built-in support for it. Compiling with -deprecation flag lets you find all places where you override a deprecated method, helping your users find suspicious code very quickly. ...
7
You can include such documentation within the XML comments, and generate LaTeX manuals, web pages and other documents from it using Doxygen. Use the <remarks> and <example> elements for the extended prose.
7
Aside from pushing for documentation (which is important), I would also suggest pushing for tests to be written (if they haven't been already and I'm willing to bet they haven't been). As Michael C. Feathers talks about in his book Working Effectively With Legacy Code, tests are a good way to deal with the cluttered code in a legacy application. Write tests ...
7
Part of the difficulty in terms of the customer writing a specifications document is that the customer often doesn't know how to translate the things the customer wants into a language which actually describes what the customer needs. While the customer may say that they want a certain behaviour to exist in a system, they are generally not so concerned with ...
6
Having all documentation in one system instead of two can be a real advantage. Things like backup & restore, versioning, global search, global search&replace, cross-linking, and, as you wrote, putting all docs in one final document, will typically work with less "friction" when you don't have to maintain two different systems with overlapping ...
5
Appropriate term is most likely incubator, this is one used by Google and Apache:
google-web-toolkit-incubator
The Official incubator of widgets and libraries for Google Web Toolkit...
Apache Incubator
...the gateway for open-source projects intended to become fully fledged Apache Software Foundation projects...
If you take a closer look ...
4
I don't know of any automated tools as such, but this is too long to put in a comment.
I'd strongly suggest starting a wiki for your project to hold user documentation. Then you can quickly draft a overall view, and gradually expand on it. Make it a requirement that when someone changes something that affects the end-user, they update the documentation to ...
4
All of the "lightweight" markup languages work well for this.
Markdown http://daringfireball.net/projects/markdown/
ReStructuredText (RST) http://docutils.sourceforge.net/rst.html
There are others. http://en.wikipedia.org/wiki/Lightweight_markup_language
I'm a fan of RST.
rst2html.py somefile.rst >somefile.html
4
You probably have the crux of why they have a high turnover in your post. You have already raised your concerns with management, make sure you have done so in a formal way pointing out the business reasons for documentation (reduced support costs and wasted resources in trying to figure out the code).
If you have raised your concerns in the correct way and ...
3
I am going to go out on a limb and say that there are none, and even if there was one, it would be ignored because the programming community is too diverse and opinionated to all agree on something. That being said, the JavaDoc/Doxygen family is as close as we are likely to get. We might see a few large camps develop, but that's it.
3
I've implemented a documentation system using MediaWiki before, and found it worked quite well for what I needed. Pros and cons below.
Pros:
Free - I've no idea what your budget is, but for me that was a key requirement
Allows in browser editing and full version control
Relatively straightforward to set up, provided you're a reasonably rounded techie
Lots ...
3
I suggest Microsoft SharePoint. It's a great portal for sharing documents in an organization with high capabilities including search (inside files), creating and managing lists, creating personal sites, versioning, etc. You can think of it as a DMS (document management system).
However, I don't know if it has any plugin for in-browser document edition, and ...
3
SQL Management Studio has the ability to add a Description for columns, but I've never found it useful, ever. I've also tried to get work to use docs, wikis and what-have-you's to document DB structure. After enough time, nobody bothers though. Release dates won't wait for anything.
A descriptive, consistent naming scheme won't fail you. Don't be afraid to ...
2
I've got Java in a Nutshell from O'Reilly for precisely that purpose.
Java in a Nutshell, 5th Edition... adds more discussion on tools and frameworks. It also offers new code examples to illustrate the working of APIs, and, of course, extensive coverage of Java 5.0. But faithful readers take comfort: it still hasn't lost any of its core elements that ...
2
There is no silver bullet. Like other aspects of programming, you need to decompose the problem and tackle one area at a time.
Here are some ideas that can (in my experience) be helpful:
Reduce the need for documentation
There are often better ways to communicate than through documents, eg. face-to-face
Identify which documents have little value and stop ...
2
Yes, you are repeating yourself if your documentation is just a simple rehash of the code.
I've seen enough of this in my days to last a lifetime:
/**
* Set the name
* @param name The name
*/
void setName (String name) { ... }
It is madness!
Instead of the above, leave obvious code to speak for itself and focus on finding areas in your code which is ...
2
I had one gig where I wrote an automated test script explicitly to generate new screenshots, and it worked quite well. Whenever the GUIs changed I merely ran that test, then copied the images to the website. It proved to be a much better system than to regenerate the screenshots by hand.
This method also guaranteed that the screenshots were consistent. We ...
2
I would use external documentation if you need to include class diagrams, graphs, formulas, images, etc. to explain how your libraries work. Include this external documentation as part of your library releases in whatever format you deem appropriate (LaTeX or otherwise). You can refer to this document from your code if you wish (e.g. "See the "Readme" ...
2
Elements to take care from process and cultural point of view:
1. Ensure that expectations are well set for what should be the content in documentation
It is important to define what is expected to be written when documentation is done. Many a times it is surprising but people make internal assumptions.
Useless comments are just as bad as no comments.
2. ...
2
You probably will want either a full traditional state diagram or a summary pseudo-state diagram.
The full diagram would have a state circle for each of the (in your example) 72 states, and each of the transitions (including self loops). Such a diagram is good for documentation and study for modifications. It is easier to deal with than the C code as it ...
2
I've seen developers write scenarios; testers write scenarios and even a product owner write scenarios. I've also had conversations explicitly designed to bring out scenarios - "Given <this other context>, when what should happen then?" - and written down the words the business use.
The best results I've had were from having a conversation with the ...
2
Some use other systems - take a look at Python's Sphinx for example, they have a all-in-one doc system that build everything (it also works for C/C++)
I always think of documentation as being separate to the code, doxygen is great, but it is for an overview of the API, not 'documentation'. For that, a wiki is great, but I prefer to use ASCIIDOC and store ...
2
Use Code Documentation, first. Add Wiki & other methods, if possible
I know, that is going to be difficult, to maintain it.
Practical answer:
But, in practical terms, the first thing that developers do, its check the code.
As a developer, I like to have external documentation, like Wiki (s), manuals. But, the first thing I do, its to review others ...
2
I would suggest to group your tables in logical domains and visualize them on a poster. You may created and prepare printable file them with the help of ER studio/SSMS.
Most importantly, naming of columns need to be closely related to domain to avoid naming further ambiguity in long run.
2
What is the requirement of such internal comment-based documentation? Is there anything in this particular type of syntax that would cause problems?
The basic requirement is that the documentation parser knows what that piece of program-text means. This is independent of what a compiler would do with it.
In this case, it helps that the grammar specifies ...
Only top voted, non community-wiki answers of a minimum length are eligible
