Product Documentation
- Mark as New
- Bookmark
- Subscribe
- Mute
- Subscribe to RSS Feed
- Permalink
- Report Inappropriate Content
‎11-28-2017 08:03 AM
Hi all,
I was wondering what general opinions there are out there on the product documentation, developer docs etc?
I'm asking because I often find them hard to use, and not as user friendly or helpful as the Wiki of the olden days.
For instance,
I just searched for 'email.body_text' in the Istanbul documentation and the developer docs. I got very little back in the search results that was immediately useful.
Do any of you good people of the community have any similar frustrations, or thoughts on how best to make use of the docs?
Jamie
- Mark as New
- Bookmark
- Subscribe
- Mute
- Subscribe to RSS Feed
- Permalink
- Report Inappropriate Content
‎11-29-2017 07:49 AM
On Wiki, each page had multiple sections. Clicking search results landed you in a comfy nest of useful information.
In many cases, Docs treats sections as whole separate pages. Now I'm clicking through a spider web of related content with no perceivable visual link.
Sometimes I remember that there's a hierarchy on the left hand side, but its almost never synched (meaning I'm scrolling through a vertical stack 1,438,982 pixels long).
EXAMPLE: DOCS SEARCH ON EMAIL VARIABLES
STEP 1: Search "email variables"
STEP 2: Click a version checklist button
I need to click it two or three times before the page refreshes.
STEP 3: Go to the sys_email variable page
1/10 the content of Wiki originally had on the same topic.
Maybe if i look around on other similar topics?
STEP 4: Look around for other email topics
FIN!
I tried a couple other things, but nothing got me to wear I wanted, so I went back to wiki and did a search. First link I clicked....
- Mark as New
- Bookmark
- Subscribe
- Mute
- Subscribe to RSS Feed
- Permalink
- Report Inappropriate Content
‎11-29-2017 08:26 AM
Thanks Robert, this is a great example. The docs page you found through the Wiki is in the search results, but it is the 6th result down:
Being the 6th result basically means that most people won't even see it. We definitely know that having good information that people can't find is the same as not having that information. The defragmentation of the content will help some with this, but we'll be looking into the search tuning to see how we can also improve it directly in the search algorithm.
I don't know if this would help with clicks for you or not, but when I search, I start from the home page (docs.servicenow.com). There are two ways to set the family filter easily from here:
- Use the red box on the left of the search box to select the family(s) you would like to search within
- Click on the family version tile that you want to search within and you are taken to that family's page. When you search from there the family version is automatically selected for the search filter.
- Mark as New
- Bookmark
- Subscribe
- Mute
- Subscribe to RSS Feed
- Permalink
- Report Inappropriate Content
‎11-29-2017 07:28 PM
So I know there's a solution coming soon for the version thing... but its only 6th result after picking a version (which is always the last thing I factor for)
Prior to that its a scroll or two down. You only know its the 6th one down because right now you know the specific page you're looking for. If you're me 24 hours ago you're clicking the top 2 or 3 links then moving on.
I get that no search is going to satisfy everyone all the time, I'm just saying docs is difficult to search, and that's exacerbated by too many pages multiplied by independent versions.
- Mark as New
- Bookmark
- Subscribe
- Mute
- Subscribe to RSS Feed
- Permalink
- Report Inappropriate Content
‎11-30-2017 12:09 AM
I get that no search is going to satisfy everyone all the time, I'm just saying docs is difficult to search, and that's exacerbated by too many pages multiplied by independent versions.
That's the current situation - hopefully that will be addressed with the page consolidation project currently underway.
I'm not sure who thought the original design was a good idea (curious to know if it was ever prototyped to see what the user experience was) but at least it's being fixed now, which is the important thing. Live n learn, eh?
- Mark as New
- Bookmark
- Subscribe
- Mute
- Subscribe to RSS Feed
- Permalink
- Report Inappropriate Content
‎11-30-2017 05:30 AM
I got a live-n-learn list that's 10x longer than the list of things I'm proud of. I don't want people getting the impression I hate Docs, or that I don't recognize how far its come along since it started. Top of that list is how much better the *spirit* of Docs is. Time was when Docs described things like a dictionary, and wiki taught you the what/how/why. Way less disparity there.
But I'll go on record saying cutting wiki off Dec10 is a bad idea, if for no other reason that its consistently better at searching Docs than Docs is.