13 Replies Latest reply on Jul 29, 2008 11:34 AM by Magpie

    Single Source Publishing


      Do you have any plans to support component level content management i.e. authoring and assembling documents from reusable components using standards like DITA?


      I''d like to collaboratively author and assemble technical manuals and teaching materials wiki style, but also have the benefit of workflow approval and project tasking.


      Forums are an excellent way to interact, I''d like to leverage the content created and as a publishing channel using Clearspace.

        • Re: Single Source Publishing

          I''d like to share more of the background to my question.


          Like Jive Software we are also software application product, as such we have technical documentation needs that have re-usable content potential over across a number of channels (manuals, teaching material, e-learning, help, knowledge bases, sales collateral, & RFP responses. How does Clearspace produce its documentation? Looking at Altassign:Confluence - it looks like they produce their documents using its own capabilities.


          We have been looking into XML component content management systems based on the DITA standard. Many of which have good workflow support -but most of which only support review comments.


          However, we like the Wiki systle approach where we can be flexible in the way we allow people to edit content themselves. The dream solution is the ability to combine the best of both worlds Wiki with publication controls and visioning. Clearspace looks like it has this right blend as a lot of content gets created and interaction happens - it seems a great opportunity to not only leverage the content but also most importantly the collaborative and community methods.


          Certainly spending just an hour or so with the hosted evaluation - I do like the product. However, you don''t as yet appear to have the ability to assemble wiki documents as fragments into larger documents. The fragments should be re-usable and have only one logical instance. This is where the DITA standard comes in with its topic maps. Being XML based there are also endless possibilities to transform the outputs. Your are already outputting RSS & PDF (would like to see others like SCORM).


          We have found some other like minded people who also see the potential and confirm the gap:







          or (slides) http://idealliance.org/proceedings/xtech05/slides/prescod/Structure%20and%20Chaos.ppt






          Do you have any plans to fill the hole between DITA and Wiki''s?


          Would level of capability is possible via the plug-in architecture?


          How big a undertaking would this be?




          Ref. to slides by Paul Prescod added



          Message was edited by: Magpie

            • Re: Single Source Publishing
              Kevin Williams

              One of our areas that we have identified for improvement is more advanced content management.  As such I have pushed this post onto our development team for consideration as the new features surrounding content management are designed and implemented.


              This is definitely something that can be done via a Plug-in/Macro.


              I could see having a "master page" that has a custom macro that pulls content from other documents.  Say you have doc1 (intro), doc2 (body), and doc3 (conclusion).  You could then create a master document, that looks like:






              And the entire document would be displayed.  I imagine this is what you are wanting?  Doing this would be relatively straight forward.

                • Re: Single Source Publishing

                  Thanks, yes this is the general idea, although we''d also need a TOC to be generated.


                  Ultimately, we''d like to also support custom manuals based on an XQuery. i.e. based on some input criteria a number of documents (and other elements) fragments are pulled together dynamically. Also a information shopping cart to search/select fragments and then compile them into a document.


                  I''m sure that you may feel that we are seeking ECM functionality and that you may want to keep things a bit lighter - indeed looser coupling via web services could be the answer. However, what is intriguing is the prospect of using a community based way of creating and engaging with people vs. a dry technically correct way.


                  We also like the idea of customers/partner participating in the creation and correction of technical documentation.

                    • Re: Single Source Publishing
                      Kevin Williams

                      Thanks for the input.  I have added a link to this thread for the developers to review when upgrading the content management functionality.  The more information you can provide on what you want to see, the better!

                      • Re: Single Source Publishing

                        I''m a technical writer at Jive catching up a bit with this thread. I wanted to comment that I''m thinking about most of the same issues you bring up -- single sourcing, structured content, multiple deliverable formats, making the most of collaboration, and so on -- but with regard to Jive''s own documentation.


                        I know what I like and have wanted in authoring environments, but I''d be very interested in hearing your ideas for possible Clearspace features that could add to support your work.



                          • Re: Single Source Publishing

                            A chance to eat your own dog food - as they say! You understand the same problem and opportunity for a software product company to combine the expression of knowledge with it''s consumption in a virtuous circle.


                            There seems to be different levels at which Single Source Publishing (SSP) can bring benefits:


                            Content fragments are authored at a level that can be re-used by including into other containers. The context being defined by the container. Along with this comes a likely need to generate a Table of Contents.


                            A further refinement on this is the ability to have ''variables'' for conditional publishing. This sophistication can help when only the context changes, but the content for that channel is basically the same i.e. avoid re-writing a version.


                            If you start looking at the standards (e.g. DITA) and the native XML database technologies often used, lots of other things become possible - like dynamic generation based on queries.


                            True single source is write-one link/include-many vs. write-once paste-many. This enables tracability which means making corrections/updates much more efficient and effective.


                            Other elements in the mix that come from the ECM world is automatic tagging based on a defined ontology. Indeed, whilst the folksonomy approach taken by Clearspace is powerful, it may not be reliable enough. A formal taxonomy may also be needed as well.


                            A key factor for assembly is the ability to find content fragments that can be reused. The clearspace linking capability shows the use can be made of tags, I really like the preview as well.


                            SSP would not be complete without the ability to transform the content into many different forms - hence the use of XML and XSLT transformations.

                            • Re: Single Source Publishing

                              The challenge/opportunity with expressing knowledge is to find the right formats for its consumption - I like the approach that Clearspace and others use for making explanations tasked based and the use of best practices.


                              Whilst formal static documentation like a user guide might still be needed, there is good potential to publish in different formats. In this sense, I don''t mean pure technical output formats like PDF or HTML, but rather application help, knowledge bases, printable manuals etc.


                              So my likely start point on this journey is to define the dimensions:


                              (1) Expression of Knowledge - see formats above and documents

                              (2) Consumption & Enhancement of Knowledge through Interactions - discussion groups, comments

                              (3) I think we also need to think about the roles involved like knowledge co-ordinates/facilitators and information architects.

                              (4) and of course the users!


                              Once we understand the knowledge domain and the roles/processes involved, we''ll be in a better position to define the functionality required.


                              Apologies for the overuse of the word knowledge - too over used. Trying not to be pretentious, I prefer the term Knowledge Enablement, rather than Management. Indeed, I''d like to find another term other than knowledge, but when we succeed people recognize that they are enabled by the sharing and access to knowledge by results they achieve - what''s in it for me.

                              • Re: Single Source Publishing
                                straut wrote:

                                Stuart - Any update on how you are using Clearspace for product documentation.


                                <div class="jive-quote">

                                I''m a technical writer at Jive catching up a bit with this thread. I wanted to comment that I''m thinking about most of the same issues you bring up -- single sourcing, structured content, multiple deliverable formats, making the most of collaboration, and so on -- but with regard to Jive''s own documentation.


                                I know what I like and have wanted in authoring environments, but I''d be very interested in hearing your ideas for possible Clearspace features that could add to support your work.




                                Love to hear what you are looking for in a authoring environment.



                                The  EmbedContent Macro provides a starting component.

                                  • Re: Single Source Publishing



                                    What's the latest on supporting Single Source Publishing?


                                    Do you use Clearspace to produce the Clearspace Documentation?



                                      • Re: Single Source Publishing

                                        Hey Magpie,


                                        It depends on the interpretation of "single source publishing" tool (I think senses of that phrase range from narrow/shallow to very broad). I think it's fair to say that our product management team is focusing on making Clearspace the best collaboration tool it can be. Collaboration-related goals include many of the issues that you and I are concerned with as content-oriented people, but not all.


                                        Having said that, I'll note that Clearspace is getting closer to supporting this kind of thing with each version. Our next version will include many improvements to content editing, for example. Be sure to take a look at that one when it becomes available shortly.


                                        I'm not using Clearspace to author docs -- at least, not yet. We still have deliverables external to Clearspace instances that we need to address. So far, our releases include an Ant-driven build process for generating PDFs and HTML with conditional markup. Clearspace is outstanding as an environment to facilitate collaboration around the content (comments, feedback, suggestions, multiple authors), but we have yet to work it into our build process (too busy writing content!). I'm eager to see what the next versions of Clearspace make possible.




                                          • Re: Single Source Publishing

                                            Thanks Steve - I agree Single Source Publishing can be a broad church, often leading to technical solution based on leveraging XML and XSLT.


                                            However, in the context of my direct question about how Jive documents are created your answer is interesting. I accept the party line about Clearspace being a collaborative tool, indeed, I absolutely agree to the point that I'd like to have my own documentation collaborative authored, be that just internal or internal & external. Maybe this could lighten your workload . Well that's the theory, and it will be interesting to see how this might pan out.


                                            I've had a play with the 2.5 beta text editor and it certainly moves the game on - the present restrictions of Wiki syntax is a limiting factor.


                                            I'd still like to see some stronger support for embedding documents. This involves some enhancements elsewhere, including adding custom metadata to help with identification and searching.


                                            I still think with some enhancements, we'd have the basics to do document assembly. It would be basisc, but it needs to be, since SSP systems are still way too complicated.

                              • Re: Single Source Publishing

                                As I'm chiming in on discussions tonight, I"ll add my feedback to this one as well...


                                A year ago I probably would have passed over this thread.  But now our tech writing team is doing a POC of Daisy CMS because they want to work on product documentation more collaboratively with our development teams.   Clearspace document authoring is currently pretty far from what we'd need to author our product documentation.  Maybe we'll be able to have Daisy and Clearspace co-exist...but right now it's confusing the engineering teams a lot about what their obligations are in each system and what they should write where.  Having a single system where we can capture people's work into a format that can be "delivered" as final product would be great.

                                  • Re: Single Source Publishing

                                    The challenge here is see if Clearspace can start to straddle two worlds. It's doing an excellent job in helping visibility, accessibility, and fostering collaborative working. However, it's ability to support more structure isn't coming through yet e.g. no template's or metadata for documents.


                                    There are some cost effective XML SSP solutions now appearing, so one thought is to look at an integration route. The issue being that you want something very simple for end users.


                                    I still can't help feeling that some simple solution could be implemented with Clearspace. They already have the UI for creating custom attributes for people (altough not leveragable on searching yet). The embeding macro shows promise in being able to pull together document fragments.