Concrete Documentation Suggestions

We have an opportunity to have some input, and I want to take advantage of it.
If you have a suggestion or an idea about how to improve
documentation, I want to hear from you. Follow this link and leave a comment.
http://dezignstuff.com/blog/2007/07/13/concrete-ideas-on-improving-documentation /
I'm looking for practical, viable suggestions, and maybe identifying what you think the problems are. (insane rants will be removed)
Matt Lombard
Add pictures here
<% if( /^image/.test(type) ){ %>
<% } %>
<%-name%>
Add image file
Upload

http://dezignstuff.com/blog/2007/07/13/concrete-ideas-on-improving-documentation /
Quote: "Example of something that will get removed: My name is Jon Banquer or cliff or neil or any one of their aliases.
Add pictures here
<% if( /^image/.test(type) ){ %>
<% } %>
<%-name%>
Add image file
Upload
ok good on you matt... if anyone has half a head up SW and stands a chance of being heard its you if they were genuinely interested in improving stuff they are quite capable of carrying out their own official survey IMHO however so I dont really hold out much hope.
As for input I've given enough clues about what to do already without writing a do list Its all been there for people who wanted to listen If they are completely at a loss for ideas they can go to the Alias help notes via the link I posted a few days ago and look at the StudioToolConcepts and Technical surfacing PDF I dont think its too hard for a reasonably bright individual to see the difference in detail and helpfulness
BTW SW managrment does suck and the new guy had better be a brisk new broom...
and PS i'm ALF ;o) and you didn't mind me saying "I am with you buddy" and "it stinks"
cheers
Add pictures here
<% if( /^image/.test(type) ){ %>
<% } %>
<%-name%>
Add image file
Upload
well matt was generous enough to publish another ALF entry so as a bonus here is another few thoughts for him re help. I didnt think this would fit on his blog comment
At 600,000 users SW has well and truly arrived in its own right so forget about catering to Autodesk 2d laggards It doesnt actually help them make a transition anyway.They need to learn to think SW style from the outset. Cleanse the notes of redundant references and terminology. If absolutely necessary put in a chapter recounting the history and evolution of engineering drawing with a nod to Autodesk
Just as you can't achieve everything relying on intuition you can't expect to describe everything with simplicity. Without bogging in thesis detail you need to describe the tool in entirety and in relation to the others available. I can't think of any better recipe for content than everyones old friends WHO,WHAT,WHERE,HOW,WHEN,WHY,IF. To say "this is a spline try pulling on the handle to see the effect" misses the requirement completely. Explain a spline, talk about CV's ,knots, continuity and the effects, shortcomings and merits and what happens to curvature combs etc. Show how me to use it best to achieve a common real task. Give me sufficient hints so I can confidently tackle something difficult. Tell me if there is a better tool for the situation or an alternative way of getting there. Point out the underlying attributes so I can plan or anticpate the outcome of extreme missions Give me a heads up if what i'm doing doesnt migrate to other programs or formats well... its all sensible stuff if you actually want to help people use what they invested in
Engineers are not stupid people.Dont underestimate them. They buy this program to achieve intelligent things and they expect they will get the full goods on it out of the box. They want to be informed about exactly what their tool is capable of or not. Clarity and directness are not the same as removing big words and keeping sentences short. If its well indexed and has links there is not such a need to keep it concise esp in electronic form cos it doesnt matter if there are 3000 pages What worked well in the circumstances of early SW and with a printed manual in mind may not be the best style to perpetuate. I find some documents very hard to read and take in in PDF form on a screen. Think about how the user has to learn the content. Sitting down under a tree with a book isnt the same experience as doing a relational search and following links,seeing a short demo or listening to a mp3 caption. In the future electronic paper may allow you to sit again under the tree but for now you are tied to a pc screen so you may as well have a bonafide multimedia approach from go not an adapted one. Actually I have confidence that SW guys given an opportunity to innovate can come up with something just as effective today as the original wired manual was in its day. Really the time has come to cast off old technology and use the new to even better complete effect. Although it has taken a while to get to the point where SW recognise the existing doesnt work as well as it needs to or perhaps they imagined it did this is an opportunity to empower users as never before with the potential already at their fingertips and they should embrace it enthusiastically. Please don't forget to check out your proposal with users before you actually commit to it though ;o)
I thank you please leave a tip in the case by the door...
Add pictures here
<% if( /^image/.test(type) ){ %>
<% } %>
<%-name%>
Add image file
Upload
On Sat, 14 Jul 2007 12:43:50 -0700, jon_banquer
Well if Matt had any doubt about you Jon, your clueless rant settled it.

http://blog.novedge.com/2007/07/an-interview-wi.html
quote from the author of the blog you link to in your signature;
[ Jon didn't respect our agreement, posting comments under fake names. Jon's authentic and fake comments are all posted from the same IP address, 72.199.251.224. I can now see that my trust in Jon was misplaced. ]
Tom
Add pictures here
<% if( /^image/.test(type) ){ %>
<% } %>
<%-name%>
Add image file
Upload

Polytechforum.com is a website by engineers for engineers. It is not affiliated with any of manufacturers or vendors discussed here. All logos and trade names are the property of their respective owners.