1
vote
1answer
86 views

Is there a tool to generate multi-goal procedural instructions? [closed]

As a user: When I have good instructions to follow I'm sure I could do just about anything. With poor instructions I end up frustrated, wasting time and probably giving up. The type of instruction I ...
0
votes
2answers
261 views

How to write comments to explain the “why” behind the callback function when the function and parameter names are insufficient for that?

How should I approach writing comments for callback functions? I want to explain the "why" behind the function when the function and parameter names are insufficient to explain what's going on. I ...
1
vote
0answers
88 views

Is there a unified source code documentation generator? [duplicate]

I'm currently working on a client's project that involves programming in multiple languages. It has gotten to the point where the amount of source code for each language has grown to such a large ...
6
votes
1answer
247 views

Is there a de facto standard documentor for Javascript?

I'm trying to document my code using JSDOC3, that has a similar syntax to PHPDocumentator / Apigen. But is there a de-facto standard for Javascript inline documentation? I think Google Closure is the ...
5
votes
1answer
557 views

Duplicating documentation on interface implementations/overrides good or bad?

So we have an interface like so /// <summary> /// Interface for classes capable of creating foos /// </summary> public interface ICreatesFoo { /// <summary> /// Creates foos ...
4
votes
1answer
1k views

Does doxygen support templates for the HTML output?

I've documented my code for doxygen, but I don't want the default HTML it gives. I know I can customize it by providing custom CSS, headers, footers, etc. (like GNOME does), and how I can add common ...
2
votes
1answer
439 views

documentation of typescript code [closed]

my question is rather short: How do I document typescript code properly? I found out that for projects becoming bigger and bigger, it is important to look at a function and immediately know ...
5
votes
2answers
141 views

Seeking advice on system documentation

I have a rating engine (it is basically an algorithm) which when I started had no formal documentation. We have created a functional specification/decomposition which is our business level document ...
8
votes
3answers
162 views

How to document experimental or incomplete APIs like @deprecated?

Is there a good term that is similar but different than "deprecate" to mean that a method or API is in the code base but should not be used because its implementation is not complete or will likely ...
1
vote
1answer
320 views

How to document unlimited argument parameters?

In PHP you can have a function take an infinite number of arguments like /** * Do abc... * * @since 1.0 * @param mixed $arg1 Arg description * @return string ...
2
votes
2answers
266 views

HTML in docblock comments?

In the PEAR standards there is no reference to HTML, if its allowed or not. http://pear.php.net/manual/en/standards.sample.php But I see some people use HTML tags like <kbd> and stuff.. So is ...
3
votes
5answers
555 views

How do you keep track of the meaning of your SQL fields?

The more SQL fields I add to my tables and the more primary/foreign keys I add the more I lose the overview for specific fields for certain scenarios like Get/Add/Delete/Update data. I use SQL ...
10
votes
7answers
886 views

Where to put code documentation?

I am currently using two systems to write code documentation (am using C++): Documentation about methods and class members are added next to the code, using the Doxygen format. On a server Doxygen ...
21
votes
4answers
945 views

Is BDD actually writable by non-programmers?

Behavior-Driven Development with its emblematic “Given-When-Then” scenarios syntax has lately been quite hyped for its possible uses as a boundary object for software functionality assessment. I ...
6
votes
5answers
425 views

Where should a programmer explain the extended logic behind the code?

I have developed a few quantitative libraries in C# where it is important to understand not only the classic information that goes with the XMLDoc comments (which contains basic information with the ...
20
votes
5answers
831 views

How-to convince company to start documenting for legacy software [duplicate]

It has been less than a year since I joined my current company. Their majority of sales have come from a single product that has been alive since the last 10 years. However, there is minimal (if at ...
4
votes
3answers
175 views

What could be some pitfalls in introducing a style guide and documentation generating software in a development team?

I'm considering using appledoc, a flavor of Doxygen for use in generating Objective-C code documentation, in order to create documentation for my company's iOS apps. The idea is that a server will ...
7
votes
5answers
476 views

Whats sort of platform should I host documentation on? [closed]

We have a web-based software product that has a growing user-base of around 200+ people. I won't go into details on our current workflow, but it involves word documents and converting to HTML and I ...
12
votes
5answers
980 views

What are the deliverables to give to the client for a web application ?

I have completed a web application which is basically developed in PHP and is just another regular web application. Usually when I deliver the final production release I just handover the code ...
3
votes
2answers
336 views

Using automated bdd-gui-tests to keep user-documentation-screenshots up do date?

Are there developpers out there, who (ab)use the CaptureScreenshot() function of their automated gui-tests to also create uptodate-screenshots for the userdocumentation? Background: Whithin the ...
2
votes
2answers
144 views

How do I follow DRY when documenting module structure and interfaces?

In this paper, it is recommended that one document the following: module structure module interfaces If I'm writing detailed module structures and interfaces in a standalone document, aren't I ...
2
votes
2answers
717 views

Best way to manage minutes of meeting

What is the best way of managing minutes of meeting on daily bases ? Do we have to manage the documents in a repository like VSS or it can be maintained in a excel sheet itself. Kindly share your ...
4
votes
1answer
396 views

How can the process of creating and maintaining documentation be improved?

I know it's a very subjective question , but this is one section of Software Engineering wherein I haven't seen any improvement in terms of how we can do it in a better way. I guess every programmer ...
0
votes
2answers
2k views

PDF or ebook Java API documentation [closed]

Since I have a long train ride to and from work I was wondering if there is a version of the Java API documentation floating around that I could put on my Kindle. It would be nice on the rare occasion ...