nav[aria-label="Primary Navigation"] { padding: 0; & ul { list-style: none; width: 100%; display: flex; flex-direction: row; justify-content: start; align-items: start; gap: 30px; padding: 0; & li { margin: 0; } & ul li { list-style: none; } } }

The worse manual ever written?

RonaldV

Hi,

I have just gone over the SP-dev-manual from a-z and have to say that I feel that this is, apart from some 'opensource' manuals that can be pretty disgusting too, must be the worse manual I have ever read. The manual lacks ever structure, high-level overview and functional explanation. Every chapter has no relation whatsoever with the previous one, has no flow and dives into the tiny little bit of detail without beginning to properlu explain what we are (on a functional level) are trying to achieve in this chapter.

To show what I mean a good example is the chapter on 'Custom Fixed Layouts' which is not reference anywhere in de rest of the doc, dives straight into the details of the xml-config, does not start with a global/functional overview of what is does (f.i. what exactly is a fixed layout?) and does not link/relate/reference to any other part of the doc. The same can be said about the chapters 'Creating Components and Templates' or 'Geo-IP SPAR and Demo Site'. F.i. 'Creating ....' starts with mentioning the existence of predefined components and then scuba-dives to 'Page tokens' (without even explaining where they can be used and how/when they are evaluated)

Anybody who (dis)agrees is invited to react!

Find more posts tagged with

Comments

Adam Stoller

While I probably agree with your general sentiment - I find it somewhat funny to read a raving review about a document when the content of the review (including the title of the thread) contain all sorts of spelling and grammatical errors to make me wonder if this is one of the "worse posts ever written?" :-)

On a more serious note - you can rant here all you want - but if you want to try to really effect change, put together an errata sheet, open a case with AIWOV, and submit your errata sheet as a documentation bug report - then get the id of the bug (if they still provide those) and let everyone else here add themselves as interested parties in seeing the bug fixed.

Migrateduser

If it's worse than the Workflow Developer's Guide then I offer my condolences.

tec_iwov

Please post any shortcomings to the manuals so we can try to improve them

josephbreese

I agree.

1. You have to read the manual a few hundred times.
2. Fail epically trying to do the simplest of tasks.
3. Review a **** load of Java docs
4. Use a really old forum that restricts 3 letter search terms (DCR, DCT, XSL, XML, WFT)
5. Get frustrated that the forum "or" searches on multiple terms
6. Post your question and frustrations and have people defend the product instead of answer your question.

Seriously, reading the doc over and over and over has actually helped me a bunch since, as you noticed, it lacks structure. Chapter 3 expands on topics discovered in chapter 7 which introduced topics covered in chapter 2.

mart2001

Just the SP dev manual? There are probably a bunch of them from Interwoven that can be nominated. :-)

Adam Stoller

Just the SP dev manual? There are probably a bunch of them from Interwoven that can be nominated. :-)

It's not a question of nomination - If you find issues with the manuals - any of the manuals - try to put your issues into intelligible words that can then be sent to support (or via private message perhaps to tec_iwov) so that those issues have a chance of being addressed in a future revision of the manual.

If you just want to ****/groan/laugh about it here - you're free to do so, but if you're actually interested in getting something better...

josephbreese

It's not a question of nomination - If you find issues with the manuals - any of the manuals - try to put your issues into intelligible words that can then be sent to support (or via private message perhaps to tec_iwov) so that those issues have a chance of being addressed in a future revision of the manual.

If you just want to ****/groan/laugh about it here - you're free to do so, but if you're actually interested in getting something better...

It's not a hand full of issues per manual, it's the whole manual multiplied by how many manuals per product. There is a fundamental organization and structure problem with them. A support ticket may look like this:

Hire a technical writing group to rewrite your manuals FROM SCRATCH! Examples don't work, deprecated code doesn't indicate replacement methods, manual does not explain why, just how to do things. That sums it all up right there.

It's kind of hard to motivate a company who doesn't want to spend any time or effort in it's developer program to help it's developers.

RonaldV

Please post any shortcomings to the manuals so we can try to improve them

I think my initial post was pretty clear on this.

k1DBLITZ

Quoting for truth.

I'll chime in on my experiences with the manual....

From an Admin perspective, just following the directions to get the products (teamsite, livesite, opendeploy) installed is a chore.

You start by following a very vague manual that already assumes you are familiar with the installation process and continually makes references to other manuals that are hundreds of pages long, which make reference to other manuals. It's very discombobulated.

I agree.

1. You have to read the manual a few hundred times.
2. Fail epically trying to do the simplest of tasks.
3. Review a **** load of Java docs
4. Use a really old forum that restricts 3 letter search terms (DCR, DCT, XSL, XML, WFT)
5. Get frustrated that the forum "or" searches on multiple terms
6. Post your question and frustrations and have people defend the product instead of answer your question.

Seriously, reading the doc over and over and over has actually helped me a bunch since, as you noticed, it lacks structure. Chapter 3 expands on topics discovered in chapter 7 which introduced topics covered in chapter 2.

Migrateduser

In which manual does it explain how to get customer code aka externals from the SitePublisher instance to the LSDS runtime? They might want to make simple stuff like that easy to find in their manuals. Just saying.

josephbreese

In which manual does it explain how to get customer code aka externals from the SitePublisher instance to the LSDS runtime? They might want to make simple stuff like that easy to find in their manuals. Just saying.

This is in the manual of Trial and Error, chapter Stay Up Late on a Saturday Because You Have a Demo on Monday.

Seriously, if you need some help PM me and I'll walk you through the process.

Migrateduser

This is in the manual of Trial and Error, chapter Stay Up Late on a Saturday Because You Have a Demo on Monday.

Seriously, if you need some help PM me and I'll walk you through the process.

No, I was pointing out an example to support the premiss of this question and hoping someone at Autonomy will end up reading it and think duh we need that in there.

FTPing the jar from:
Interwoven\TeamSite\local\config\lib\content_center\livesite_customer_out
to
/opt/Interwoven/LiveSiteDisplayServices/runtime/web/WEB-INF/lib
Then changing directories to
/opt/Interwoven/LiveSiteDisplayServices/runtime
in order to run
/opt/Interwoven/LiveSiteDisplayServices/runtime/web/run.linux.sh stop
and
/opt/Interwoven/LiveSiteDisplayServices/runtime/web/run.linux.sh start

was so intuitive I found it in the manual of "Pay a Consultant to Explain Trial and Error, chapter Stay Up Late" since my first cracks at it failed.

chietala

I'm going to have to agree with everything that is being said here. Not only is the manual written poorly I think error reporting needs work. For instance this is an error I am getting when I push pages out to production.

"The custom error module does not recognize this error."

Thanks for talking in circles, it's really helpful =/. Also love it when you get a whole stack trace back but no real indication where things went wrong.

The amount of reading and trial and error that you spend on trying to get this thing to work right could be spent better by just rolling your own CMS. For the amount of money a customer pays for this product, the whole thing feels like a rush job.

PaulW

i think its a big call to say its the worst ever written. there are plenty of manuals that are way worse. is it 100% accurate and consistent? No. But it does cover the product pretty fully.

Binettoid

Part of the problem here is that the manual is written by the engineers, instead of technical writers. The engineers assume SO much, and of course from their point of view (which is about 5cm from the trees) it all makes sense. Unfortunately the result is a "Manual" that is actually a list of "how to" tasks.
This is only useful once you know what you are trying to achieve. As someone who was new to TeamSite (7.1, 7.2) at the beginning of this year, I have spent months reading this "manual" and thinking,
"That's all very well but WHY would I want to do that?"

This manual, quite apart form any technical errors, narrative mistakes and downright omissions, of which there are some choice examples, is certainly NOT the worst manual ever written. It is, however, a superb example of how NOT to write a manual.
Considering the relatively high cost and complexity of the product, you'd expect some of that money to go toward a manual that explains how the overall product works, an example approach, what the execution order of things are, etc. and perhaps how to dynamically link to content, to name just a few basic things that are massively important but not described (adequately) in the documentation. Compound this with the fact that our "install package" download was missing install files, necessary jar files, documentation and to this day does not work as documented.

I particularly like the way in which, following a build, the functionality of the Java externals does not change. Eventually, when you have pulled all your hair out, you add in enough debugging to significantly change the byte-size of the classes and lo and behold, your new functionality starts working.
Oh and another one is the huge difference between the way things behave in preview and runtime LSDS - beautiful!

Hey, I 've had worse though. ;-)

gzevin

hey, are you a newbie? Smiley Happy

This is as good or as bad as anything AIWOV has produced. Very typical of them, and since it's become Autonomy, the quality that used to be dubious, is MUCH MUCH MUCH worse. The tech support is MUCH MUCH MUCH WORSE. The quality of the software is the same. Bad.

vpatel

I am wondering if you anybody on this thread has looked at the re-vamped SP Dev guide that came out with TS 7.2? With this updated manual, AU/IW spent some time trying to create a simpler outline and more specific examples.
If you haven't looked at that manual, I would encourage you to look at it and then providing any constructive criticism / feedback (i.e. with specifics onto what you'd like to have changed) would be much much beneficial in helping ALL stakeholders :-)!

My $0.02!

gzevin

I am wondering if you anybody on this thread has looked at the re-vamped SP Dev guide that came out with TS 7.2? With this updated manual, AU/IW spent some time trying to create a simpler outline and more specific examples.
If you haven't looked at that manual, I would encourage you to look at it and then providing any constructive criticism / feedback (i.e. with specifics onto what you'd like to have changed) would be much much beneficial in helping ALL stakeholders :-)!

My $0.02!

good, you are not trying to spin the support!

While I have not seen the 'newer' SP guide (no interest in this so far), I can tell that the old FP manual is a bad as it used to be, and, because of the bug that I am about to lodge with the support, it's even wrong now.

scatter_multi_series.png

RonaldV

Well,, IWOV has improved itself ever further: the "LiveSite Content Services
Technical Reference Guide 7.1" beats ALL its concurrents in worse-ness.

And if you want to know why: it is completely unreadable.

herald10

I am the new victim of SP dev guide. My sincere suggestion is to run this document through a technical writer. The author of this document seems technically sound but articulation is definitely not his forte. So all a technical writer needs to do is just rewrite the sentences first. That will be a good start.

Just my 2¢.

groups_chart.rptdesign

Migrateduser

I wasn't even looking for this post, but got sucked into looking at it because I'm about to try approaching SP and seeing how to put a site together in it. Can't wait to see the manual being discussed.

Migrateduser

I think there's a 'missing' SP guide called "Organizational Site Management using SitePublisher and LiveSite." Here's why:

After working on installing 7.2.1 on Linux (got that working nicely in general), I'm back to looking at SitePublisher's capabilities - and that brought me back to this posting.

I've got to agree, once again, with the gist of this thread - there seems to be no concept within the SP Developer Guide / SP Users Guide combo of:
1) how to get started, organizationally, with SP/LS
2) how to plan the high level usage & management of SP/LS within an organization
3) how to create and utilize a 'site template'
4) approaching global localization of sites
5) organization around developing and managing templates and components
6) strategies to manage site look and feel using .css or other methods

and more..

I tend to think that the product set can accommodate the above capabilities, but if we have to to figure out every little bit of how to manage a set of sites using the product set, it's most likely that we won't even get out of the starting blocks here.

Here are 2 examples of what we -could- do with this type of info:
- replace our current DreamWeaver / Moveable Type / Sharepoint intranet content with a centralized 'do it yourself' system that gives each department a choice of initial site templates to start with.
- replace our set of branded sites (developed with a variety of tools) with a centrally administered system based on a common set of templates and components that would easily enable global look and feel changes.

There's a lot of great AIWOV 'glossy info' (marketing literature) about how the product set enables the above types of capabilities - but there's a big 'magic happens here' gap between the glossy info and any implentations.

I'm back to the manuals to see what I missed. If any of you have some recommendations (training materials? Best Practices whitepapars?) on filling the 'magic' gap in the 'glossy info' > magic > implementation set of documentation, this might be a good place to post it.

KoenDeSmet

The administration part of the products are fairly good described.
But the developer part lacks some critical info that can only be found back trough devnet or support service itself (or even ,and mostly not documented at all).

A nice example : How does one create spar files.

There could easely be a seperate guide in there specifically for creating spar files.

Another example :
Customisation for the livesite/sitepublisher part. What lacks are proper guidelines for do's and dont's for customising livesite in terms of performance with some genuine examples.

And the one thing that REALLY would help is an example case/ training case for developers that jump into a new domain (workflows/dct's/opendeploy/datadeploy/IDOL/search/...),where the most common parts are tackled.

Instead of pumping money to more and more indians at techsupport ,the money should be flooding to good developer guide writers. (I have here a gut feeling too that engineer part is getting overwhelmed by support requests too ,given that the response times are getting longer and longer too . Creating proper guides helps here a lot to offload those engineers ,and let them work on bugfixes and enhancements).

I agree on the rtfm , but also to the gutfm (give us the f... manual)

Seriousy, the easier a product is to customise/develop/maintain ,the easier you can sell it. Extended guides and training material is a must have.
(I would prefer to see more teamsite on the market too ...)

Koen - For 6 years teamsite admin now ...

gzevin

The administration part of the products are fairly good described.
But the developer part lacks some critical info that can only be found back trough devnet or support service itself (or even ,and mostly not documented at all).
..

In the 7.2.X the CGI callouts do not work if you write them the way it's described in the manual. And most of our legacy callouts DO NOT work in the newer versions of TeamSite. So what IWOV is saying is...... it's a 'documentation bug'. LOL.