New forum sticky posts: Your opinion please...

[System1]

Those of us who have been around for a while generally know how things
work. I’m not sure I can say the same for some casual forum visitors. As
we try to respond to posts in the various forums we encounter many of
the same issues no matter where the post originates:

• The question is posted in the wrong forum. Volunteers with the
  appropriate expertise are less likely to see the post.
• The issue as presented is too vague. Specific details are needed so
  we ask follow-up questions before we can diagnose the problem.
• Sometimes expectations are unrealistic.
• Sometimes the requested information is available in the product
  documentation but the poster hasn’t looked, perhaps because (s)he is
  unaware it is available online or hasn’t been able to locate it.
• Others may have encountered the same issue and it is already
  documented in a TID but the poster hasn’t checked.

And the list goes on…

What we would like to do is make people more aware of the many
resources available to them before they post so they can decide for
themselves which resource(s) might be most appropriate. We would also
like to remind them how to use the forums most effectively.

The support forums are -product- focused. While TAG websites contain
vast amounts of information, most of which are organized into categories
and can be located from the main header, there is currently no grouping
of information by product. The -product- support forums are an ideal
place, perhaps even the only place, to make that information available.
We are thinking of using sticky posts to accomplish that.

The challenge, of course, is to decide what to include and how to
present it. I know visitors to this Community Chat Forum are never shy
when it comes to expressing opinions so we would like to get some of
that feedback before we proceed.

I have prepared a sample post that might be used in OES-Linux Install
forum. I will post it as a reply to this post so we have a concrete
example of what we have in mind.

–
Kevin Boyle - Knowledge Partner
If you find this post helpful and are logged into the web interface,
show your appreciation and click on the star below…

KBOYLE’s Profile: http://forums.novell.com/member.php?userid=19359
View this thread: http://forums.novell.com/showthread.php?t=464861

[system]

Welcome to the OES Linux Install forum.

We have assembled a list of OES specific resources to help you decide
how to best answer your question or resolve your specific issue. If you
choose to ask for help from our forum volunteers, please post your
question in the appropriate forum and refer to the ‘Novell Forums
FAQ’ (http://forums.novell.com/faq.php?faq=novfor#faq_novellgen).

Related Forums

This link provides access to specific ‘OES: Linux’
(http://forums.novell.com/novell-product-discussions/file-networking-services/open-enterprise-server/oes-linux/)
forums where you can post questions dealing with:

• Administration
• Install
• Networking
• Printing
• Storage and Backup
• Linux Web Services
• Domain Services for Windows

If you know or suspect you have a Linux issue, you may find the help
you seek in one of the ‘SUSE Linux Enterprise Server’
(https://forums.suse.com/forumdisplay.php?8-SUSE-Linux-Enterprise-Server)
forums.

Requested Information

In addition to any other information you feel is relevant, please
include the following with your post using
Code:

tags (i.e. the # formatting option) to make the output more readable:

• The exact error messages, if any, as they are shown.
  (You may find other messages and clues in the log files located in
  /var/log, especially in /var/log/messages.)

• Output from these commands run from a command prompt.

• cat /etc/*release

• uname -a

Additional Product Specific Resources

You may find answers to your some of your question more quickly if you check out these resources:

• ‘Current OES 11 Documentation’
  (http://www.novell.com/documentation/oes11/oes11_toc/data/index-stand.html)

• ‘Recent Technical Information Documents (TID) - Open Enterprise
  Server’ (http://www.novell.com/newsfeeds/rss/tids/tids_oes.xml)

• ‘Open Enterprise Server Cool Solutions | Novell User Communities’
  (http://www.novell.com/communities/coolsolutions/openenterpriseserver)

• ‘The Novell Knowledgebase’ (http://www.novell.com/support/)

• ‘Open Enterprise Server Product page’
  (http://www.novell.com/products/openenterpriseserver/)

Other Available Resources

• You may be entitled to -free installation support- within thirty
  days of purchasing the product
• If you have purchased maintenance and it is still current you
  may be able to open a Service Request to obtain help with your
  issue at no additional cost.
• ‘Support: Submit a Service Request: Details’
  (http://support.novell.com/contact/getsupport.html)
• ‘Customer Center’
  (https://secure-www.novell.com/center/regadmin/jsps/home_app.jsp)
• ‘Novell Services’ (http://www.novell.com/services/)

Note: Please do not reply to this post as this thread has been closed. If you have any comments or wish to report an issue concerning this post, please create a new thread in ‘Feedback About These Forums’ (http://forums.novell.com/novell-product-discussions/product-neutral/feedback-about-these-forums/) and be sure to refer to this forum.

–
Kevin Boyle - Knowledge Partner
If you find this post helpful and are logged into the web interface,
show your appreciation and click on the star below…

KBOYLE’s Profile: http://forums.novell.com/member.php?userid=19359
View this thread: http://forums.novell.com/showthread.php?t=464861

[system]

I think you are fighting a losing battle.

People will always post in the wrong place. Can’t say I haven’t done it
myself.

Questions are often vague because the person honestly doesn’t know what they
are doing or have limited forum experience. Not much you can do except hand
hold.

Unrealistic expectations are the norm today, just look at job descriptions.

RTFM? Nobody does that. Better to layoff the documentation specialists.
Sorry to be blunt, but docs are usually obsolete by the time they are
written. There are so many obsolete docs on the internet that it’s pretty
embarrasing, but oddly, still relevant if that’s the tech
you are working with. The problem is distinguishing between the two which
is why people end up posting about stuff that is ‘in the manual’.

Many answers are available via Google, except those that are locked up and
chained into proprietary systems which ultimaltely leads to questions being
posted in forums that are available elsewhere for ‘a fee’. Not sure what you
do about that when answers are deemed a profit center.

Having said that, ‘stickies’ are helpful assuming someone takes the time to
read them. Too many stickies are a nuisance, via nntp it is irrelevant. Of
course someone posting via nntp is probably going to know their way around
but not a guarantee. I know with nntp I have been called out because I
should have posted elsewhere, but I was unaware of an added forum since I
don’t often refresh my forum list.

Overall I think stickies are useful and probably a positive addition, but
unlikely to be a cure all.

Good Luck!
-G

[system]

On Tue, 12 Mar 2013 21:14:40 +0000, GofBorg wrote:
[color=blue]

People will always post in the wrong place. Can’t say I haven’t done it
myself.[/color]

I don’t think Kevin thinks this will prevent 100% of instances where
people post in the wrong place. Doing that certainly would be a losing
battle.

But if it can be reduced by, say, 20% - that’s not a bad thing.
[color=blue]

RTFM? Nobody does that. Better to layoff the documentation specialists.[/color]

Ouch (I’m a technical writer now by trade, and I work on documentation a /
lot/).

I could write mountains about what’s wrong with the state of
documentation today - the biggest problem, though, is pretty simple - doc
tends to be /descriptive/, and users don’t want to be told what they’re
looking at. They /know/ what they’re looking at, and a well-designed UI
is intuitive enough that you don’t have to be told what each control
does. (And if it isn’t, that’s a UI design problem, not a doc problem).

Documentation needs to be focused on what people actually /do/ with
software.

Working in Novell Training in planning upcoming training offerings, I
used to push what my former boss once said: If he had to fix a hole in
his roof, he didn’t want a roofing class. He wanted to fix the hole in
his roof.

Documentation is like that. It needs to be procedure-oriented,
describing how to do something and why you do it. Training then becomes
about things like advanced configuration and more depth on the “why” and
“what to do when it breaks”.
[color=blue]

Sorry to be blunt, but docs are usually obsolete by the time they are
written. There are so many obsolete docs on the internet that it’s
pretty embarrasing, but oddly, still relevant if that’s the tech you are
working with. The problem is distinguishing between the two which is why
people end up posting about stuff that is ‘in the manual’.[/color]

Sadly, a lot of documentation is written not by technical writers but
by writers. Technical writing is not a well-understood field by those
who aren’t actively working in it - you have to have an aptitude for
software, and an ability to learn the software in spite of the fact that
there’s little documentation (and what there is was written by the people
who wrote the code - ie, coders, not writers).

It also needs to be managed in a way that allows it to be updated quickly
as the product changes. That’s something that - as you say - doesn’t
happen as effectively as it should.

Doc is all about knowledge management, and effectively structuring
knowledge so people can find what they need to do the task they’re
working on /right now/, and so they can find relevant information when
they get stuck.

Jim

Jim Henderson, CNA6, CDE, CNI, LPIC-1, CLA10, CLP10
Novell Knowledge Partner

[system]

Jim Henderson wrote:
[color=blue]

Ouch (I’m a technical writer now by trade, and I work on
documentation a / lot/).[/color]

I’ll refrain form commenting on the rest of your post even if it is a
hot topic and needs to be aired.

I was hoping to get feedback on the sticky posts in this thread. If
anyone wants to respond to your documentation comments, perhaps they
would be kind enough to start a new thread.

–
Kevin Boyle - Knowledge Partner
If you find this post helpful and are logged into the web interface,
show your appreciation and click on the star below…

[system]

Jim Henderson wrote:

[color=blue]

I could write mountains about what’s wrong with the state of
documentation today - the biggest problem, though, is pretty simple -
doc tends to be descriptive, and users don’t want to be told what
they’re looking at. They know what they’re looking at, and a
well-designed UI is intuitive enough that you don’t have to be told
what each control does. (And if it isn’t, that’s a UI design
problem, not a doc problem).

Documentation needs to be focused on what people actually do with
software.[/color]

I’m glad I’m not the only one frustrated by this! For example, I hate
it when I have a field I need to fill out while installing software.
The field label doesn’t give enough information, so I look at the
docs…and all they say is: “This is where you enter ”.
Really??? No kidding! Tell me something I don’t know! Sheesh.
[color=blue]

Documentation is like that. It needs to be procedure-oriented,
describing how to do something and why you do it. Training then
becomes about things like advanced configuration and more depth on
the “why” and “what to do when it breaks”.[/color]

Yes! How and Why! I wish more doc writers provided that information!

Ken

[kgroneman]

See what you’ve done Jim? Thread drift R Us.

–
Kim - 3/13/2013 9:40:05 AM

[system]

On Wed, 13 Mar 2013 13:42:53 +0000, KeN Etter wrote:
[color=blue]

I’m glad I’m not the only one frustrated by this! For example, I hate
it when I have a field I need to fill out while installing software. The
field label doesn’t give enough information, so I look at the docs…and
all they say is: “This is where you enter ”. Really??? No
kidding! Tell me something I don’t know! Sheesh.[/color]

I was installing a product about 6 months ago and needed a port number.
The instructions said something to the effect that it’s the [component]
web server port.

Would you know that I couldn’t find it anywhere? What’s more, there was
a problem with the installation and an SSL certificate that was needed
didn’t get issued, so the service wouldn’t even start, so a lsof -i
wouldn’t tell me, either.

I was working on doc for that product - and changing from descriptive to
“targeted” (as it’s called). We dropped that product’s doc from 1300
pages to 800 just by getting rid of redundant information that described
what was on the screen (and an outdated/unused development guide).
[color=blue]

Yes! How and Why! I wish more doc writers provided that information![/color]

The good news is that I know one group of companies (our hosts) who are
moving in that direction for a number of products.

I hope the trend continues.

–
Jim Henderson, CNA6, CDE, CNI, LPIC-1, CLA10, CLP10
Novell Knowledge Partner

[system]

I agree with your points Jim. I have done tech writing in the past as well.
Probably the best example of being steered wrong by docs that I can think of
was a README file I encountered in a ‘product who must not be named’. It
stated something to the effect of: If X then set b during initial setup. So
I diligently followed the README directions. Lo and behold the system flat
didn’t work.

Call to PAID support, since this product does not allow access to the KB via
free sources. After much back and forth:

engineer: ‘Why do you have ‘b’ configured?’
me: ‘It’s in the README.’
engineer: ‘Wow, you read it? Ignore it, it’s out of date you need to set it
to a.’

[system]

On Wed, 13 Mar 2013 18:53:09 +0000, GofBorg wrote:
[color=blue]

I agree with your points Jim. I have done tech writing in the past as
well. Probably the best example of being steered wrong by docs that I
can think of was a README file I encountered in a ‘product who must not
be named’. It stated something to the effect of: If X then set b during
initial setup. So I diligently followed the README directions. Lo and
behold the system flat didn’t work.

Call to PAID support, since this product does not allow access to the KB
via free sources. After much back and forth:

engineer: ‘Why do you have ‘b’ configured?’
me: ‘It’s in the README.’
engineer: ‘Wow, you read it? Ignore it, it’s out of date you need to set
it to a.’[/color]

That makes me facepalm so hard I get a headache when I see that happen.

Jim

–
Jim Henderson, CNA6, CDE, CNI, LPIC-1, CLA10, CLP10
Novell Knowledge Partner

[system]

kgroneman wrote:
[color=blue]

See what you’ve done Jim? Thread drift R Us. :-)[/color]

But it is a good point!

And chat without thread drift just wouldn’t be chat!

[system]

Jim Henderson wrote:
[color=blue]

On Wed, 13 Mar 2013 13:42:53 +0000, KeN Etter wrote:
[color=green]

I’m glad I’m not the only one frustrated by this! For example, I
hate it when I have a field I need to fill out while installing
software. The field label doesn’t give enough information, so I
look at the docs…and all they say is: “This is where you enter
”. Really??? No kidding! Tell me something I don’t
know! Sheesh.[/color]

I was installing a product about 6 months ago and needed a port
number. The instructions said something to the effect that it’s the
[component] web server port.

Would you know that I couldn’t find it anywhere? What’s more, there
was a problem with the installation and an SSL certificate that was
needed didn’t get issued, so the service wouldn’t even start, so a
lsof -i wouldn’t tell me, either.

I was working on doc for that product - and changing from descriptive
to “targeted” (as it’s called). We dropped that product’s doc from
1300 pages to 800 just by getting rid of redundant information that
described what was on the screen (and an outdated/unused development
guide).[/color]

And in the process you actually made the docs worth something!
[color=blue][color=green]

Yes! How and Why! I wish more doc writers provided that
information![/color]

The good news is that I know one group of companies (our hosts) who
are moving in that direction for a number of products.

I hope the trend continues.[/color]

I agree!

[system]

GofBorg wrote:
[color=blue]

I agree with your points Jim. I have done tech writing in the past as
well. Probably the best example of being steered wrong by docs that
I can think of was a README file I encountered in a ‘product who must
not be named’. It stated something to the effect of: If X then set b
during initial setup. So I diligently followed the README directions.
Lo and behold the system flat didn’t work.

Call to PAID support, since this product does not allow access to the
KB via free sources. After much back and forth:

engineer: ‘Why do you have ‘b’ configured?’
me: ‘It’s in the README.’
engineer: ‘Wow, you read it? Ignore it, it’s out of date you need to
set it to a.’[/color]

Wow…its one thing for docs to be out of date…but a product
readme??? That should always be up to date!

[system]

On Thu, 14 Mar 2013 12:53:32 +0000, KeN Etter wrote:
[color=blue][color=green]

I was working on doc for that product - and changing from descriptive
to “targeted” (as it’s called). We dropped that product’s doc from
1300 pages to 800 just by getting rid of redundant information that
described what was on the screen (and an outdated/unused development
guide).[/color]

And in the process you actually made the docs worth something![/color]

Yep.

There are descriptive bits that are helpful (like parameter documentation
and config file contents), but UI descriptions are generally useless -
and a lot of work to update when (and it’s almost always /when/ and not
“if”) the UI changes.
[color=blue][color=green][color=darkred]

Yes! How and Why! I wish more doc writers provided that
information![/color]

The good news is that I know one group of companies (our hosts) who are
moving in that direction for a number of products.

I hope the trend continues.[/color]

I agree![/color]

Jim

–
Jim Henderson, CNA6, CDE, CNI, LPIC-1, CLA10, CLP10
Novell Knowledge Partner

[system]

On Thu, 14 Mar 2013 12:52:38 +0000, KeN Etter wrote:
[color=blue]

kgroneman wrote:
[color=green]

See what you’ve done Jim? Thread drift R Us. :-)[/color]

But it is a good point!

And chat without thread drift just wouldn’t be chat! :-)[/color]

and here I thought thread drift was babble …

[system]

On Mon, 18 Mar 2013 20:58:37 GMT, Bob Crandell bob@donttreadon.me
wrote:
[color=blue]

On Thu, 14 Mar 2013 12:52:38 +0000, KeN Etter wrote:
[color=green]

kgroneman wrote:
[color=darkred]

See what you’ve done Jim? Thread drift R Us. :-)[/color]

But it is a good point!

And chat without thread drift just wouldn’t be chat! :-)[/color]

and here I thought thread drift was babble …[/color]

in any other forum but this one, sure…

[system]

As a new person (or like me, somebody who only comes in every year or so
when I’m upgrading things) I would find this type of sticky very useful
to scan through and potentially solve my own problem, rather than asking
and waiting for an answer.

–
Kathryn Carruthers

kathcarruthers’s Profile: http://forums.novell.com/member.php?userid=21
View this thread: http://forums.novell.com/showthread.php?t=464861

[system]

kathcarruthers wrote:
[color=blue]

I would find this type of sticky very useful[/color]

Thanks Kath,

The sticky posts have been added to the seven OES Linux sub-forums.

I’ll be watching the “Feedback About These Forums” forum for feedback.
http://forums.novell.com/novell-product-discussions/product-neutral/feedback-about-these-forums/

–
Kevin Boyle - Knowledge Partner
If you find this post helpful and are logged into the web interface,
show your appreciation and click on the star below…