11 Replies Latest reply on Jul 8, 2014 11:31 AM by marya.devoto

    Best Practices for Documentation?

    lhenriksen

      I am an outside consultant being asked to move extensive product documentation (currently in Word) to Jive. 

       

      1) Is this a recommended use of Jive?

      2) Are there best practices for accomplishing this?

      3) Would it be more efficient to move to Jive using HTML exported from something like InDesign?

      4) Is the Jive CSS available for class/styles in predefined HTML?

      5) Is it better to put individual PDF pages into Jive rather than trying to move in a Word page document?  Is the PDF fully searchable in Jive?  Any best practices for posting PDFs?

      not very WYSIWIG which significantly impacts editing time.   Are there ways to improve the WYSIWIG between edit and view?

       

      I've noticed that Jive Software documentation is not in Jive which makes this request a concern for me.  I'd appreciate your best advice on this.

        • Re: Best Practices for Documentation?

          Great questions. People often ask about this! We see Jive getting better for documentation all the time, but it still has some gotchas (and if we ever get a really solid DITA connector, well, we will be our own first customers). To be clear, a good number of our customers absolutely do publish in Jive. It isn't necessarily the best platform for large, highly structured documentation sets that interlink a lot (like ours), but as a knowledge base or for focused projects it can have a lot of value, and it's very useful to have the documentation become part of the Jive site search.

           

          Here are some ideas for creating a good documentation experience in Jive without too much pain:

           

          • Yes, it's possible to leave anything in Word docs and upload them. The content will still be searchable and Jive users will be able to comment on them and (if you give them permission) edit them. If you have a lot of Windows users and plan to have user-modifiable docs, your users could potentially use Jive for Office to edit locally and update: Jive for Office also will merge multiple users' edits and comments. It is Windows-only though.
          • If you use native Jive documents instead, and you're using an HTML source, you can create a doc, edit it in HTML mode, and paste HTML into the editor. Then toggle back to the WYSIWYG and edit that way to make sure it looks the way you want.
          • I don't have experience with InDesign output so I don't feel comfortable saying how the HTML would render.
          • You can add inline attributes to elements and styles in the HTML code, but there isn't any way to add or modify styles. You're stuck with how the Content Editor does styles.
          • If you have longer topics or want to combine short ones, Jive can add an automated in-document Table of Contents.
          • Categories are a good way to organize multiple docs to be findable inside a space. (You may or may not be able to create spaces if you aren't a Jive admin, so you might have to get someone else to do this part.) You can also put documentation in different groups to make it easier for users to browse or search only in that area.

           

          How extensive a doc set are we talking about? For customers who have heavy document management needs, we typically recommend reaching out to Jive Professional Services for assistance.

            • Re: Best Practices for Documentation?
              lindahaviland

              "Great questions. People often ask about this! We see Jive getting better for documentation all the time, but it still has some gotchas (and if we ever get a really solid DITA connector, well, we will be our own first customers). "

               

              Hi Maya -

              I never really looked at Jive's own documentation before the last month or so, so I can't compare to earlier content. I do see your doc now in the Documentation community and wonder if your answer from above is different now because I think you may be using a DITA connector. Is that right? I know the content is authored in Oxygen/DITA and transformed to WebHelp and PDF. Is JIVE able to deliver your content almost seamlessly, or does the JIVE Documentation Community use special sauce to deliver the content.

              I'm starting to look at a solution that includes Oxygen/DITA to WebHelp and PDF, similar to what you've done....

              thanks for your help

              Linda

                • Re: Best Practices for Documentation?

                  Hmm, I'm not sure what documentation you're referring to when you say it is "in the Documentation community." Our main docs are living on a separate site at docs.jivesoftware.com. If you want to see the two flavors of output, you can click through from there. The Jive 7 docs are still in the old Eclipse Info Center format: the Cloud docs use an HTML5 webhelp built on the command line using a plugin we purchased from Oxygen.

                   

                  There is also quite a lot of information elsewhere in the Jive Community that isn't part of our official documentation set, and those documents (here is an example: Getting Started with the Jive Node SDK) are created in Jive and not DITA.

                   

                  We do have a customer partner at SuiteSolutions who is working on a solution for injecting DITA content into Jive, so you could reach out to SuiteSolutions if this is a path you're considering. There are also some promising future developments at Jive which should help with organizing content in a Jive site.

                • Re: Best Practices for Documentation?
                  tmaurer

                  Hi Marya,

                   

                  One thing I feel I need to point out is that with the current Jive implementation of Office preview, Excel and Word documentation isn't viewable on a mobile device. This is a HUGE drawback, IMO, and one that has caused some to pause before moving content over from whatever system they were/are using.

                  • Re: Best Practices for Documentation?
                    paintchic42

                    Marya DeVoto - do you have any examples of external communities using Jive to publish documentation that you could share?