[trotski]

There are numerous places where we are asked to check the software's documentation. Does anyone of you really go through all those ugly pages? Can't they be more user friendly?

[jjsaw5]

I can't tell you the last time I looked through hard copy documents for software. I usually use the on-line documentation which almost always has a "Search" feature that makes finding what I need easier.

[P4L]

I have to work with documentation every day. Since I am a specialist, I have to document just about everything that I do. If I am ever out someone has to take my spot for some of the reports that I run each morning.

[RedSonja]

We have to document everything. I always try and write everything down, because next week I have no idea why I did it that way. I usually put more detail in the comments. Once you have established a good set of documents you can keep reusing the format and structure.

In the safety critical review all documents are reviewed, and they look better if they have gone through several versions from the start of the project and so on. We have to check them into CVS now and again, so no cheating. Some QS people don't even read them, they just flick through.

But the documents have to be right, because I have interfaces to other people's code and they to mine. Having said that, you can document an interface with a well commented .h file and a good example. The point of documenting here is mostly to provide an alibi when things go wrong - "but I said in my design document that there is a possible error source here".

[GWatt]

I wish everyone who wrote documentation would do so in the style of Javadoc. That, too me, is by far the most readable, easy to navigate standard. The ADC Docs are OK, but could stand improvement. The MSDN Library is disgusting. The QT docs are pretty much like javadoc, but they don't have the side menu.

[Moonbat]

GWatt, on 22 Oct, 2008 - 06:44 AM, said:

The MSDN Library is disgusting.

Quoted for truth.

Usually, I can find the answer to a programming question by Googling it, like "OOP with C++" or whatever. Reading documentation is a last resort for me.

I work mostly with PHP, and their online documentation is straightforward and easy to use. I like it a lot.

[RodgerB]

Moonbat, on 23 Oct, 2008 - 06:47 AM, said:

GWatt, on 22 Oct, 2008 - 06:44 AM, said:

The MSDN Library is disgusting.

Quoted for truth.

Quoted for lies.

[Moonbat]

RodgerB, on 22 Oct, 2008 - 01:59 PM, said:

Quoted for lies.

It has that stupid stationary scroll window because the horizontal menu bar takes up like a third of the page.

Also, many important elements don't have examples. One example is cout in the Visual C++ section.

[Pwn]

GWatt, on 22 Oct, 2008 - 06:44 AM, said:

I wish everyone who wrote documentation would do so in the style of Javadoc. That, too me, is by far the most readable, easy to navigate standard. The ADC Docs are OK, but could stand improvement. The MSDN Library is disgusting. The QT docs are pretty much like javadoc, but they don't have the side menu.

If I have to rely on MSDN, I usually spend twice as much time hunting than I do creating the program. There is a lot of information in MSDN, but finding it isn't easy and their search function hardly ever gives me what I'm looking for. Also, when I do find what I'm looking for, it's usually called something that would never even cross my mind.

[KYA]

I feel the same way about the java API.

[Nykc]

I like the man pages.