Re: [Framers] "Modularity" and FrameMaker
Actually, true modularity is an interesting problem, and may not have much to do with FrameMaker, per se. DITA is probably a good place to start for this, and FrameMaker does support DITA -- It's what I use for my DITA editing. But that alone doesn't make your documentation modular. I implemented a system that loads the docs into the client, per request. On init it loads the TOC and the search index. Then for each request it loads each topic one at a time. The topics are all on the server as raw DITA -- the client transforms the DITA on the fly, for each request. It does dynamic delivery, but all the dynamic composition happens in the client. I think this is an important point -- you can decide how to dynamically respond at the last moment, as the client displays the response to the request. I have some standard entry points where you can process a dynamic response... On init (build TOC and Search), per specific request (say, when calling search, or when displaying a specific conref), and per topic load. For modular docs, this system can dynamically load content from different sources and merge it into the rendered help system. So for our product, we support remote plugins that add features to the product. You can document the remote service within that component, and when help loads it asks the remote service for its docs. It stitches the remote docs in with the main docs, and it all looks like a single piece. When you say modular docs, this is what I think of. Aggregating content from a number of service nodes, and stitching them together as a single piece. As the network evolves and micro services take over, I believe this is what we'll see. cud From: "framers-requ...@lists.frameusers.com" To: framers@lists.frameusers.com Sent: Friday, January 22, 2016 2:00 PM Subject: Framers Digest, Vol 7, Issue 23 Send Framers mailing list submissions to framers@lists.frameusers.com To subscribe or unsubscribe, visit http://lists.frameusers.com/mailman/listinfo/framers_lists.frameusers.com or, via email, send a message with subject or body 'help' to framers-requ...@lists.frameusers.com You can reach the person managing the list at framers-ow...@lists.frameusers.com When replying, please edit your Subject line so it is more specific than "Re: Contents of Framers digest..." Today's Topics: 1. Modularity and FrameMaker (McGill, Deb) 2. Re: "Modularity" and FrameMaker (Fei Min Lorente) 3. Re: "Modularity" and FrameMaker (Yves Barbion) -- Message: 1 Date: Thu, 21 Jan 2016 21:15:53 +0000 From: "McGill, Deb" To: "framers@lists.frameusers.com" Subject: [Framers] Modularity and FrameMaker Message-ID: Content-Type: text/plain; charset="us-ascii" Hi, I can speak to a portion of your questions. We also use unstructured Frame 12 on Windows 7 and ePublisher to generate Help systems for the products we develop and manufacture at this site (instruments and software). We have been using "agile" for about 6 years now but it was never really successful until we adopted the JIRA development tool (Atlassian) about a year ago. For products and accompanying documentation, there is always a minimum viable product that must be completed before you can think about releasing the product. But after that, everything is supposed to be modular...so, say the team wants to add a new experiment type or sampling application to a software product, the product owners write the requirements for it by adding a JIRA story with a detailed description (sometimes a power point is attached), the programmers plan it for the next agile sprint by adding effort points to the story and breaking it down into small (typically 1-4 hour) tasks, the documentation person adds a related pointed story with tasks for the same or the following sprint (you can only document in the same sprint if the programmers finish it early (say in week 1 or 2 of a 3 week sprint). Then the sprint starts, the programmers do their work, the QA person tests the very day the programmers get it finished or have something to look at, the documentation person at least gets started during that sprint. At the end of the sprint, there is a demo for the key stakeholders. They give a thumbs up or a list of changes. Then stories are added for the next sprint to implement the changes and the documentation person gets their proof edits completed, QA finishes testing and the whole thing is considered done and a release COULD happen. In reality, we plan releases with a bunch of new features implemented rather than one or two. However, as the release date nears, there is a lot of back and forth about what must get in and what can wait for the next release. That's the idea of agile. Every story in JIRA i
Re: [Framers] "Modularity" and FrameMaker
Hi Eric Agile, modular documentation, reuse ("bits of information about a product that could be shared in multiple manuals and possibly other documents"): all good reasons to "go DITA". An agile User Story is a standalone feature that is meant to answer one customer need. Similarly, a DITA topic is a standalone piece of content that answers a single question, for example: - How can I do task X? - What is a given concept? - Where can I find a given component or software command? So, in DITA, the idea is that you write standalone topics, which you then assemble into a DITA map. A DITA map corresponds (more or less) to a FrameMaker book, but the difference is that each DITA topic is a separate XML file, whereas the components in a FrameMaker book are usually chapters in a binary FrameMaker format. This means that reusing information in unstructured (binary) FrameMaker is more difficult than it is in DITA. In DITA, you can reuse topics as a whole in various DITA maps, but you can also reuse parts of a topic, such as a section of a topic or even individual sentences or paragraphs. You are already using unstructured Frame 12, which supports DITA, and the DITA-FMx plugin supports DITA even better: http://leximation.com/dita-fmx/featurecomparison.php Y ou can google "DITA" and "Agile" and you'll find lots of pointers, but here are some interesting ones: - www.embedded.com/design/prototyping-and-development/4230902/DITA-and-the-death-of-technical-documentation-as-we-know-it - www.slideshare.net/IXIASOFT/agile-content-development-and-the-ixiasoft-dita-cms?qid=443e7abe-6abe-4772-866b-b627a215cea9&v=default&b=&from_search=2 - http://www.slideshare.net/nabayanroy/agile-meets-dita-developing-user-documentation-in-an-agile-environment?qid=7d2e654f-15a6-48a4-ae87-4f13f669b22f&v=qf1&b=&from_search=1 And if you'd like to see how your content would look like in DITA, feel free to send me a sample FrameMaker book. Cheers -- Yves Barbion www.scripto.nu ___ This message is from the Framers mailing list Send messages to Framers@lists.frameusers.com Visit the list's homepage at %http://www.frameusers.com Archives located at %http://www.mail-archive.com/framers%40lists.frameusers.com/ Subscribe and unsubscribe at http://lists.frameusers.com/mailman/listinfo/framers_lists.frameusers.com
Re: [Framers] "Modularity" and FrameMaker
Hi Eric: We adopted Agile practices almost two years ago and we're still working out best practices (but that will always be an ongoing task), so I can tell you what I've found so far with documentation in FrameMaker. Basically, what you've been told about modular documentation is not necessary for working with an Agile development group. All I've had to do is allow developers to document their little bit of code development that they achieve in a sprint (in our case, 2 weeks). We've defined their coding task as "done" when it's documented, so I get the documentation in incremental pieces as the sprints go by. I suppose this makes the documentation "modular" in the sense that they can easily find the place where they need to document things and there's a minimum of ripple effect, or the ripple effect is obvious (like cross-references), but I haven't had to break up our documentation. We're still using a book paradigm. Working Agile means that a lot of documentation gets reworked over and over again, but on the bright side, it always reflects the product at the end of the sprint, so the documentation and the software are always synchronized. I don't know anything about Polarion, so I've just looked up the website, and after a few minutes of reading and watching the overview video (so take this with a grain of salt), it looks like a project and process management tool, but I don't see why your engineers would want to access FrameMaker's API from it. Unless you currently do your requirements and specifications documents in FrameMaker? Back to what I do know. We are using Atlassian's tool called Jira to help us manage our workflow in an Agile way. It has an Agile plug-in so that we can create epics and stories, plan sprints, track velocity, and so on. If all this is Greek to you, you should read up on Agile practices. There's loads of information on the internet, so I won't bother sending you links. And every company has their own implementation of Agile depending on corporate culture, industry, etc. so even with the reading, you should find out what your engineers are doing, and make sure they make you part of the team. You should be sprinting along with them. What you described as "modular" is really re-usable; that is, the same information can be re-used in different places. That doesn't have anything to do with working Agile. Maybe you should find out why they think you'd suddenly have to start sharing information between manuals. Fei Min Lorente Senior Technical Communicator and Business Process Analyst - Message: 1 Date: Wed, 20 Jan 2016 15:52:44 -0800 From: eric_isaac...@selinc.com To: framers@lists.frameusers.com Subject: [Framers] "Modularity" and FrameMaker Message-ID: Content-Type: text/plain; charset="us-ascii" Hi! I'm looking for some guidance for a challenge I was given. My workplace is wanting to make products using Agile development and by making things more "modular". I don't know that management knows what this means exactly, but I have been tasked to see how our product literature can and should fit in with this idea. The basic idea as I understand it is that we would have bits of information about a product that could be shared in multiple manuals and possibly other documents (such as requirement specifications). One engineer involved mentioned that in order to manage all of the software development, the company plans to use Polarion (and he asked me about Frame and API possibilities--I found the Frame Developer Center page and passed that along to him). I also know that Atlassian tools are also being used (I believe in regards to the Agile development initiative), but I do not understand how those two sets of tools are related. Has anyone had any experience with similar concepts or with the specific tools as they relate to using FrameMaker? How does structure documentation fit in with this, if at all? Any pointers to things I can read or consultants to consult or training I can attend? Anything at all would be helpful. I feel like I'm on my tip-toes and the water is up to my neck already. I know, I know, breathe Thanks! Fyi: We're currently using unstructured Frame 12 in Windows 7. We output PDF for print and the web as our deliverable. Eric Isaacson Product Literature Manager -- next part -- An HTML attachment was scrubbed... URL: <http://lists.frameusers.com/pipermail/framers_lists.frameusers.com/attachments/20160120/ec351a0c/attachment-0001.html> ___ This message is from the Framers mailing list Send messages to Framers@lists.frameusers.com Visit the list's homepage at %http://www.frameusers.com Archives located at %http://www.mail-archive.com/framers%40lists.frameusers.com/ Subscribe and unsubscribe at http://lists.frameusers.com/mailman/listinfo/framers_lists.frameusers.com
[Framers] Modularity and FrameMaker
Hi, I can speak to a portion of your questions. We also use unstructured Frame 12 on Windows 7 and ePublisher to generate Help systems for the products we develop and manufacture at this site (instruments and software). We have been using "agile" for about 6 years now but it was never really successful until we adopted the JIRA development tool (Atlassian) about a year ago. For products and accompanying documentation, there is always a minimum viable product that must be completed before you can think about releasing the product. But after that, everything is supposed to be modular...so, say the team wants to add a new experiment type or sampling application to a software product, the product owners write the requirements for it by adding a JIRA story with a detailed description (sometimes a power point is attached), the programmers plan it for the next agile sprint by adding effort points to the story and breaking it down into small (typically 1-4 hour) tasks, the documentation person a dds a related pointed story with tasks for the same or the following sprint (you can only document in the same sprint if the programmers finish it early (say in week 1 or 2 of a 3 week sprint). Then the sprint starts, the programmers do their work, the QA person tests the very day the programmers get it finished or have something to look at, the documentation person at least gets started during that sprint. At the end of the sprint, there is a demo for the key stakeholders. They give a thumbs up or a list of changes. Then stories are added for the next sprint to implement the changes and the documentation person gets their proof edits completed, QA finishes testing and the whole thing is considered done and a release COULD happen. In reality, we plan releases with a bunch of new features implemented rather than one or two. However, as the release date nears, there is a lot of back and forth about what must get in and what can wait for the next release. That's the idea of agile. Ever y story in JIRA is carefully prioritized, so the most important stuff gets done first and gets a lot of focus...as it should be. We have sprint meetings for 15-30 min max twice a week that include the product owners, all the programmers, and the documentation person so everyone hears about the progress and any problems or delays as the sprint proceeds. We also squeeze in some usability testing...but that is a subject for another e-mail chain. For your other question, we use a lot of shared text and minimal conditional text. This is because our instruments are not that similar to each other. Maybe someone else can talk about the other tool you mentioned, or other tools for creating documentation modules that can be reused. Deb McGill Sr. Technical Writer in Madison, Wi -Original Message- From: Framers [mailto:framers-boun...@lists.frameusers.com] On Behalf Of framers-requ...@lists.frameusers.com Sent: Thursday, January 21, 2016 1:00 PM To: framers@lists.frameusers.com Subject: Framers Digest, Vol 7, Issue 22 Send Framers mailing list submissions to framers@lists.frameusers.com To subscribe or unsubscribe, visit http://lists.frameusers.com/mailman/listinfo/framers_lists.frameusers.com or, via email, send a message with subject or body 'help' to framers-requ...@lists.frameusers.com You can reach the person managing the list at framers-ow...@lists.frameusers.com When replying, please edit your Subject line so it is more specific than "Re: Contents of Framers digest..." Today's Topics: 1. "Modularity" and FrameMaker (eric_isaac...@selinc.com) -- Message: 1 Date: Wed, 20 Jan 2016 15:52:44 -0800 From: eric_isaac...@selinc.com To: framers@lists.frameusers.com Subject: [Framers] "Modularity" and FrameMaker Message-ID: Content-Type: text/plain; charset="us-ascii" Hi! I'm looking for some guidance for a challenge I was given. My workplace is wanting to make products using Agile development and by making things more "modular". I don't know that management knows what this means exactly, but I have been tasked to see how our product literature can and should fit in with this idea. The basic idea as I understand it is that we would have bits of information about a product that could be shared in multiple manuals and possibly other documents (such as requirement specifications). One engineer involved mentioned that in order to manage all of the software development, the company plans to use Polarion (and he asked me about Frame and API possibilities--I found the Frame Developer Center page and passed that along to him). I also know that Atlassian tools are also being used (I believe in regards to the Agile development initiative), but I do not understand how those two sets of tools are re
[Framers] "Modularity" and FrameMaker
Hi! I'm looking for some guidance for a challenge I was given. My workplace is wanting to make products using Agile development and by making things more "modular". I don't know that management knows what this means exactly, but I have been tasked to see how our product literature can and should fit in with this idea. The basic idea as I understand it is that we would have bits of information about a product that could be shared in multiple manuals and possibly other documents (such as requirement specifications). One engineer involved mentioned that in order to manage all of the software development, the company plans to use Polarion (and he asked me about Frame and API possibilities--I found the Frame Developer Center page and passed that along to him). I also know that Atlassian tools are also being used (I believe in regards to the Agile development initiative), but I do not understand how those two sets of tools are related. Has anyone had any experience with similar concepts or with the specific tools as they relate to using FrameMaker? How does structure documentation fit in with this, if at all? Any pointers to things I can read or consultants to consult or training I can attend? Anything at all would be helpful. I feel like I'm on my tip-toes and the water is up to my neck already. I know, I know, breathe Thanks! Fyi: We're currently using unstructured Frame 12 in Windows 7. We output PDF for print and the web as our deliverable. Eric Isaacson Product Literature Manager ___ This message is from the Framers mailing list Send messages to Framers@lists.frameusers.com Visit the list's homepage at %http://www.frameusers.com Archives located at %http://www.mail-archive.com/framers%40lists.frameusers.com/ Subscribe and unsubscribe at http://lists.frameusers.com/mailman/listinfo/framers_lists.frameusers.com