10 Replies - 1311 Views - Last Post: 26 October 2008 - 02:08 PM

#1 trotski  Icon User is offline

  • D.I.C Head

Reputation: 0
  • View blog
  • Posts: 151
  • Joined: 04-September 08

Time when Documentation got a better look

Post icon  Posted 22 October 2008 - 04:58 AM

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?
Is This A Good Question/Topic? 0
  • +

Replies To: Time when Documentation got a better look

#2 jjsaw5  Icon User is offline

  • I must break you
  • member icon

Reputation: 90
  • View blog
  • Posts: 3,060
  • Joined: 04-January 08

Re: Time when Documentation got a better look

Posted 22 October 2008 - 05:09 AM

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.
Was This Post Helpful? 0
  • +
  • -

#3 P4L  Icon User is offline

  • Your worst nightmare
  • member icon

Reputation: 34
  • View blog
  • Posts: 2,788
  • Joined: 07-February 08

Re: Time when Documentation got a better look

Posted 22 October 2008 - 05:27 AM

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.
Was This Post Helpful? 0
  • +
  • -

#4 RedSonja  Icon User is offline

  • D.I.C Head
  • member icon

Reputation: 10
  • View blog
  • Posts: 172
  • Joined: 04-September 08

Re: Time when Documentation got a better look

Posted 22 October 2008 - 06:31 AM

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".
Was This Post Helpful? 0
  • +
  • -

#5 GWatt  Icon User is offline

  • member icon

Reputation: 278
  • View blog
  • Posts: 3,078
  • Joined: 01-December 05

Re: Time when Documentation got a better look

Posted 22 October 2008 - 06:44 AM

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.
Was This Post Helpful? 0
  • +
  • -

#6 Moonbat  Icon User is offline

  • D.I.C Regular
  • member icon

Reputation: 36
  • View blog
  • Posts: 424
  • Joined: 30-June 08

Re: Time when Documentation got a better look

Posted 22 October 2008 - 12:47 PM

View PostGWatt, on 22 Oct, 2008 - 06:44 AM, said:

The MSDN Library is disgusting.

Quoted for truth. :P

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.
Was This Post Helpful? 0
  • +
  • -

#7 RodgerB  Icon User is offline

  • D.I.C Lover
  • member icon

Reputation: 66
  • View blog
  • Posts: 2,284
  • Joined: 21-September 07

Re: Time when Documentation got a better look

Posted 22 October 2008 - 01:59 PM

View PostMoonbat, on 23 Oct, 2008 - 06:47 AM, said:

View PostGWatt, on 22 Oct, 2008 - 06:44 AM, said:

The MSDN Library is disgusting.

Quoted for truth. :P

Quoted for lies.
Was This Post Helpful? 0
  • +
  • -

#8 Moonbat  Icon User is offline

  • D.I.C Regular
  • member icon

Reputation: 36
  • View blog
  • Posts: 424
  • Joined: 30-June 08

Re: Time when Documentation got a better look

Posted 22 October 2008 - 03:11 PM

View PostRodgerB, 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.
Was This Post Helpful? 0
  • +
  • -

#9 Pwn  Icon User is offline

  • D.I.C Regular

Reputation: 19
  • View blog
  • Posts: 458
  • Joined: 25-November 07

Re: Time when Documentation got a better look

Posted 26 October 2008 - 10:09 AM

View PostGWatt, 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.
Was This Post Helpful? 0
  • +
  • -

#10 KYA  Icon User is offline

  • g++ jameson.cpp -o beverage
  • member icon

Reputation: 3106
  • View blog
  • Posts: 19,145
  • Joined: 14-September 07

Re: Time when Documentation got a better look

Posted 26 October 2008 - 01:28 PM

I feel the same way about the java API.
Was This Post Helpful? 0
  • +
  • -

#11 Nykc  Icon User is offline

  • Gentleman of Leisure
  • member icon

Reputation: 731
  • View blog
  • Posts: 8,644
  • Joined: 14-September 07

Re: Time when Documentation got a better look

Posted 26 October 2008 - 02:08 PM

I like the man pages.
Was This Post Helpful? 0
  • +
  • -

Page 1 of 1