Tag Info

Hot answers tagged

22

How about a logical semantically correct naming system that avoids duplication, tautology and abbreviations? 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! :-)


20

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 ...


18

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, ...


16

No. Keep everything that you need to rebuild anything else. If it's auto-generated then you can go back to any point in the history of your repository and build it again. Why keep it?


11

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 ...


10

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. ...


8

I think the list should include: The non-technical requirements (there was such a document, right?) The technical requirements A "decisions" document (if there was one) explaining why some decisions were made over others. This might already be in a different requirements or architecture document, but we usually do this separately for Big Decisions. The ...


8

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 ...


8

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.


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

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

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 ...


6

It is popular to write documentation in the same file as the code and extract that using a >software to generate documents. Yes, that is popular - for software libraries and their documentation. I guess you are talking about that kind of docs (and not, for example, user manuals). And that often results in cumbersome source file. Well, that is ...


5

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 ...


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

In addition to the really good answer of FrustratedWithFormsDesigner I'd like to say what the non technical documents include (as we did it): the analysis data: what did the customer tell you when you first talked about requirements? the offer you made: the product requirement document and the functional specification document which together act as a ...


4

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 ...


4

Automatically generate documentation from tests/docstrings/code Correct. Find a tool that fits your language and creates documentation from comments embedded in the code.


4

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 ...


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 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" ...


3

Follow whichever documentation is applicable for your project from the following.You may already have some of them. Technical documentation: Details about PHP and information on how it is useful for the project Details about the back end and information on how it is useful for the project Information on Database connectivity along with suitable pictures ...


3

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 ...


3

Use Code Documentation, first. Add Wiki & other methods, if possible I know, that is going to be difficult, to maintain it. Practical answer: 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, it's to review the code ...


3

I've never seen anything like this in other APIs, since experimental or incomplete features have nothing to do in a public API. Since you have no choices, just put a clearly visible warning that the part of the API is subject to change.


3

There's nothing which is as big as PHPDoc, but we're using airbnb, which already has over 2.000 stars and more than 350 forks on github, so it's used in a lot of projects.


3

The documentation generator is built in. The fact that it outputs XML instead of your favourite format is a different matter. http://msdn.microsoft.com/en-us/library/b2s063f7.aspx "When you compile with /doc the compiler will search for all XML tags in the source code and create an XML documentation file. To create the final documentation based on the ...


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

Be Wary The potential documentation that you could give the client is virtually endless. Additional time required to generate documentation you don't already have is unpaid. Why does the client want this documentation (over and above the source code)? What will be done with it? Who is it for? The answers to these questions will help narrow the scope of ...


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 ...



Only top voted, non community-wiki answers of a minimum length are eligible