I'm documenting a few methods I wrote in C# that deal with parsing tokens. Due to some technical restraints in other areas of the system, these tokens need to take the form of XML elements (i.e., <tokenName />). I'd like to put the format of those tokens in the summary statement itself. However, this throws an error: Badly formed XML -...
Let's say you want to provide an example url in documentation somewhere. The correct thing to do is use example.com, since that is the defined location for such things and anything else you come up with is likely to be actually registered somewhere and serving up who knows what to your readers. My questions is, what do you do if you ne...
I've found some similar questions (here, here, and here) asking about storing documents into version control. I have a more specific requirement and general question. The specific requirement is that I want to use Git. The more general question is, how should documents (for design, test, general practices, tips, etc, of a project) be sto...
While creating an application there are decisions we make, like the naming or calling conventions, format of data etc. Where should I document this? Options: Within the code, at the top. Within the code, where such decision are being effected, e.g. declaring variables, defining functions etc. Separate document. The list is not exhau...
Hi, Can you recommend any resources for learning Django? I have python experience but I've never used Django before. What did you use when you were first learning? I'm particularly interested in Tutorials, code examples and any books that you find particularly good. Best, Bruno ...
I'm trying to find info on the p method in Ruby. It seems to produce internal info on the properties of a class but when I try to search for it I get every word that has the letter p in it. ...
I seem to be forever going back to the Colouring-In Department (Marketing) and other product teams within the company I work for, trying to impress upon them what a software developer needs by way of well-formed requirements. This isn't in technical geek-speak, either. It's plain English, lots of pictures and small words with a Word te...
I know this is pretty subjective, but here it is: what documentation format (e.g. PDF, CHM, etc.) would you recommend for the user-guide in a small-scale, open-source application? Is this really just personal choice/preference, or are there compelling reasons to choose one format over another? For clarity: I'm not asking about tools fo...
Is there a straightforward way to take docbook content and convert it into DokuWiki content? So far I've only found the DokuWiki plugin that will interpret docbook content and output it in XHTML, but this happens on every page load. I would like to find a way to convert docbook content directly to DokuWiki's native formatting syntax so ...
How do I filter out the Silverlight documentation when I'm developing WPF application in VS2008? It's very annoying to get the help for the Silverlight version of the class when I press F1. I'd prefer not to remove the documentation for Silverlight altogether since I will need it in the future, but some way to choose between WPF and Sil...
Lately I've been dealing with Magento (a PHP eshop framework) which makes extensive use of XML files to determine how it should behave. Seeing as documentation isn't Magento's strong suit, I've come to a point where it would help a lot if I started keeping a record of the possible configurations of these XML files; what element can go wh...
A google search reveals nothing useful. Does Perl have a javadoc equivalent for its modules? (Update -- I'm aware of perdoc, but that is more like a man page, which is hard to scan to find functionality... I'm looking for a function/operation list (w/ descriptions) similar to javadoc's presentation or php's documentation) ...
In reading about SCM (software configuration mgt, not supply chain mgt), I have seen mention of a "Bill of Materials" as a document provided with a build. What goes into the Bill of Materials document, and what is its purpose? Is this a commonly used document? ...
If I understand correctly, extjs 2.02 is the last LPGL version. But I think it's a little difficult to use without the API documentation as extjs.com no longer carry it. Did you face this very same issue? ...
What is out there on conventions and tools for documenting python source code? ...
Folks, I'm creating a new WCF Service and started with my Service interface. Looks something like: public interface ISomethingService { /// <summary> /// some description /// </summary> /// <version>2.13.0</version> /// <copyright>2009 by myself</copyright> /// <author>Marc Scheune...
I'm a newbie to msbuild and tfsbuild and I would like to setup the automated build system. I have multiple teams (set up as TFS projects), each with their own products ,. each product consisting of many features (think business layer, gui, tooling as separate features). I need a concise / high-level documentation on msbuild and tfsbuil...
I find myself sometimes writing documents which usually consider 2 parts of a project's plan: Requirements Analysis By analysis, I mean the different possible ways that we could meet our requirements. My analysis usual includes mock-ups of UI or DB schemas or anything related. It also compares the pros and cons of 3 or 4 different ...
My work tends to involve using tools and libraries from elsewhere, rather than providing this stuff for external consumption. But for what we do internally, "documentation" means providing information that concisely enumerates the functionality for others to use. By habit we tend to generate something that looks like UNIX man-pages, but ...
Folks, I'm facing this problem here: I'm designing my second larger batch of WCF services which external parties will consume. For the first batch, I used a strict "contract-first" approach: manually created the WSDL and XSD files, and from those, generated my service and data contracts and implemented my WCF service. Worked ok, I was...