11 Replies Latest reply on May 4, 2008 8:27 PM by steve222

    Creating Help/docs for our end users inside our Clearspace implementation

    AmandaS

      Hi - I posted a similar question a while ago on the doc forum looking for a best practice.  Based on that this seems like it's really more of a feature question or request.

       

      We've implemented Clearspace, made a number of customizations and rolled it out internally.  Our users need online Help and Help documents specific to our implementation.  We couldn't find a great way to do this.  What we've done so far is create a Help space.  We used the HTML widget on the home page to produce our version of the Quick Start guide and we copy and paste that to another file and check it in to our SVN.  We've written some documents in this space as well.  We added a persistent Help link throughout our site that will take users to the Help space.

       

      We would have preferred to have been able to have documentation be global to the system vs. in a separate space.  Also, the lack of powerful editing with anchors tags etc. is really noticeable when you try to author documentation in the system.

       

      We see that Jive hosts it's own documentation in HTML files rather than in Clearspace documents.  Is that what we should all be doing too?   We'd really prefer to not have to do that because of the overhead,  delay, as well as limitations on who can author that causes.  That's why we've done what we've done so far.

       

      Anyway, net net is that I'm asking if there have been any thoughts or considerations around this at all yet.  Are we in the minority in needing/wanting to provide Help and docs inside our implementation?

        • Re: Creating Help/docs for our end users inside our Clearspace implementation

          Hi ashenon,

           

          As the doc writer at Jive, I write most of the documentation for Clearspace (a few bits have come from other folks). So I’ll chime in here with some responses to your questions. I have my own thoughts about where I'd like to see us go, and I can share those, too, if you're interested.

           

          I understand your need for content specific to your context. You’re not alone there, and I’ve talked with folks here about how we can better address some customers’ desire for content that’s more easily tailored to their needs. I can say more about my hopes, but what you’ve done (doc content in its own space) sounds like a good solution for the time being. People know where to look and the content is searchable that way (it should be found when they search across your Clearspace instance, too).

           

          I’ve looked at many of the same questions you have for the last year and a half. I agree with you that Clearspace can be a challenge for editing longer content or content that includes complex formatting. The editor itself is improving with each release, so its limitations will decrease over time.

           

          Here’s my sense of what you’re trying to get from docs in Clearspace. I hope you’ll help by clarifying a bit.

           

          • Help that’s available from every page. Do you mean context-sensitive help? I’m assuming that users can search your content from every page on which there’s a search box. Do you mean merely a help menu?

          • Better support in the editor for the specific challenges in writing doc content.

          • Doc content in a place where people can collaborate on it. How do people where you are collaborate? Do they comment on the content? Make changes to the topics themselves? As Jive updates its Clearspace documentation for new features and other changes, what are your plans for updating your content while hanging on to your customizations?

           

          I’d be very interested in hearing about other challenges and goals you have with respect to docs in Clearspace. In particular, I’m curious as to whether your interest in having docs inside the implementation is about ready editing by your users or merely immediate visibility. How important is collaboration on the documentation?

           

          Thanks for the post!

           

          Steve

            • Re: Creating Help/docs for our end users inside our Clearspace implementation
              AmandaS

              Hi Steve -

               

              Thanks for the reply.  Both immediate visibilty and collaboration is important to us.  We don't have a committed tech writer on our project so everyone on our team has to write docs - some people are better than others.  So, it's nearly always the case that a document gets started and others update, change and improve it.  Since writing the docs is a bit like pulling teeth for many people it's a lot easier to be doing it in the system where we can all easily see what's going on. 

               

              On these questions:

              • Help that’s available from every page. Do you mean context-sensitive help? I’m assuming that users can search your content from every page on which there’s a search box. Do you mean merely a help menu?

                • ashenon: context-sensitive help would be fabulous but a way to search help specifically, that is easy and intuitive, would go a long way.  I don't think that searching the help space is intuitive to people.  They can learn to do that but it's not a practice that they would expect. 
              • Better support in the editor for the specific challenges in writing doc content.

                • ashenon: yes!  anchor tags are a biggie here as well as more sophisticated formatting (HTML) as you often want these documents to be more professional looking.  Going even further would be the ability to construct documents or guides.  By that I mean that perhaps I want a user to see a "Configuring Your Project" Quick Start Guide which is an aggregation of a number of documents and I don't want them to just see a list of all those documents. 
              • Doc content in a place where people can collaborate on it. How do people where you are collaborate? Do they comment on the content? Make changes to the topics themselves? As Jive updates its Clearspace documentation for new features and other changes, what are your plans for updating your content while hanging on to your customizations?

                • ashenon: It would great if Jive considered re-branding when its docs are authored.  This could make it much easier for us to keep up to date with merging docs.  Right now we are just taking what we think is important and copying it.  Since we're writing end user documents, that isn't too much currently.  We haven't entirely committed to how we are going to collaborate on docs.  Our team authors them all so we collaborate fully.  Our users are just commenting on docs currently.  That may evolve over time - conceptually we would love it if others contributed and maybe we will at least create a "tips and tricks" area that is open for that or give certain people outside our team the ability the author and edit the help docs.

               

              Thanks again.

                • Re: Creating Help/docs for our end users inside our Clearspace implementation

                  What do you mean by “re-branding”? Some way of changing the look and feel to match yours?

                   

                  FYI, here are a few things I’d like to take a look at when there’s time. I don’t speak for the product management team, so take these as my fervent hopes rather than feature plans. In general, I think content that’s inline in the UI -- or immediately available from it -- is better than a separate “help browser.”

                   

                  • A help link. We don’t have one and weren’t sure whether customers would need it, given the positive feedback about how easy Clearspace is to use.

                   

                  • A documentation widget. People could customize space/community home pages or personal home pages with it if they want doc visibility. They could keep it around as long as they want and get rid of it when they’re ready. When I’ve mused about this, the widget has a list of content in the docs (maybe hierarchical, TOC-style) and an ability to search the content. I imagine pointing the widget at a local (in-house) server or at ours.

                    Actually, you could do something like this now by using the RSS Subscription widget on your home page, where the RSS URL brings in content tagged with, say, “documentation” or some such. The URL might look like this: https://example.com/community/feeds/tags/documentation

                   

                  • Context-sensitive help. I imagine being on a project page and seeing a few links off to one side -- “How do I assign a task to someone?”, “What can I use a project for?”, etc. This would be particularly useful in the admin console, where the UI is more involved, with lots of settings that could use context.

                   

                  There are others -- DITA-based content that could be re-branded and re-packaged into other formats, smaller doc chunks that could be mixed/matched (as you suggest for your project quick start guide), deploying searchable docs at our site and exposing them with OpenSearch, all docs (not just developer content) in one of our Clearspace instances, etc.

                   

                  Now if I could just get our developers to stop coding features for me to write about

                    • Re: Creating Help/docs for our end users inside our Clearspace implementation
                      AmandaS

                      Hi Steve -

                       

                      By re-branding I mean re-naming first and then look and feel second (maybe just changing screen shots).  E.g. is there a very fast way (not search and replace) to change "Jive Software" to our company name and "Clearspace" to our site name.  This "re-brands" the documentation for our implementation of the product.  We would still have to re-write the docs for any functionality that we've added or changed.

                       

                      I understand the doc widget idea but I'd have to say our preference would be to not take up screen real estate with doc - we'd just want it very easily accessible any time someone needs it.

                       

                      As far as the need for end user documentation or help, we've had requests for things like: "Getting Started", "How to configure your space", "Why should I use tag groups - they don't make sense to me", deeper detail on using the plain text editor, how to insert images into the formatted text widget, definitions of how the different content types should be used in our system as well as a description of the information architecture.

                       

                      Also, the requests for "Getting Started" documentation aren't just about how to use the specific features, they're also about best practices for starting a space off on the right foot.  Many of our teams are now agreeing on document naming conventions and formats as well as tagging conventions ahead of time because the teams that didn't do that started to feel lost a little while into actively using the app.  Then they were also asking us for ways to guide users to content better.  But I'm digressing now... ;>

                       

                      As a side note, I saw this post in the feature discussion that is a bit similar to some of the requests I made earlier in this thread:  http://www.jivesoftware.com/community/thread/26840?tstart=0

                       

                       

                      Thanks a lot.

                        • Re: Creating Help/docs for our end users inside our Clearspace implementation

                          By re-branding I mean re-naming first and then look and feel second (maybe just changing screen shots). E.g. is there a very fast way (not search and replace) to change "Jive Software" to our company name and "Clearspace" to our site name. This "re-brands" the documentation for our implementation of the product. We would still have to re-write the docs for any functionality that we've added or changed.

                           

                          Yep, that's what I thought you meant. We've talked about this, and I think that moving our content into a structured form (such as the DITA model I mentioned in my earlier message) might be one solution. A model that supports variables -- placeholders for terms, product names, and so on that are expected to change among deliverables -- would let our customers (and us at Jive) do alternate builds of the content with a custom set of values. So I imagine a scenario in which we give you a set of documentation source files with those placeholders built in, along with a description of how you can use your own values for the variables and build your own version of the content. DITA doesn't yet formally support variables, but there's a workaround that might make this possible. I don't see why one of the outputs couldn't be wiki markup you could paste into Clearspace. (By the way, I have an XSLT stylesheet that goes most of the way for transforming our XHTML docs into our wiki markup. Let me know if that would be useful for you.)

                           

                          Thanks for the details about the content you're finding you need. Some of that's on the list, but some of it's new to me. It's a big help!

                           

                          Steve

                  • Re: Creating Help/docs for our end users inside our Clearspace implementation

                    It is funny that I just happened to logon to the Jive Developer site and see this posting because I was making similar comments to our technical provider (I am the site administrator), but I am not as much concerned about documentation specific to our instance (I can write that) so much as better documentation for me and other site administrators like me. If it is a question of resources, I have plenty of evening time to do some contract writing. 

                     

                    For example -- and this is a big example -- I have been completely in the dark about how to enable and set-up the new features that have come with 2.0 (customization of the home page, document sharing, projects).  There was a webinar showing us what the new features were, but nothing accompanying it to show us how to use them. 

                     

                    In terms of help for myself as well as my users, searchable help files, like you get with traditional software programs, would be a great addition.