Product Documentation

Jamsta1912
Tera Guru

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

27 REPLIES 27

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"


find_real_file.png


STEP 2:   Click a version checklist button


I need to click it two or three times before the page refreshes.


find_real_file.png



STEP 3:   Go to the sys_email variable page


1/10 the content of Wiki originally had on the same topic.


find_real_file.png


Maybe if i look around on other similar topics?



STEP 4:   Look around for other email topics



animation motion GIF


find_real_file.png


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....


find_real_file.png



someone anxiety GIF


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:


find_real_file.png



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:


  1. Use the red box on the left of the search box to select the family(s) you would like to search within

                  find_real_file.png


  1. 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.

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.


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?


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.