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: "[email protected]"
<[email protected]>
To: [email protected]
Sent: Friday, January 22, 2016 2:00 PM
Subject: Framers Digest, Vol 7, Issue 23
Send Framers mailing list submissions to
[email protected]
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
[email protected]
You can reach the person managing the list at
[email protected]
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" <[email protected]>
To: "[email protected]" <[email protected]>
Subject: [Framers] Modularity and FrameMaker
Message-ID:
<blupr07mb01966d9e6befc17c868be66f2...@blupr07mb019.namprd07.prod.outlook.com>
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 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:[email protected]] On Behalf Of
[email protected]
Sent: Thursday, January 21, 2016 1:00 PM
To: [email protected]
Subject: Framers Digest, Vol 7, Issue 22
Send Framers mailing list submissions to
[email protected]
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
[email protected]
You can reach the person managing the list at
[email protected]
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 ([email protected])
----------------------------------------------------------------------
Message: 1
Date: Wed, 20 Jan 2016 15:52:44 -0800
From: [email protected]
To: [email protected]
Subject: [Framers] "Modularity" and FrameMaker
Message-ID:
<of3273420e.ef747bf2-on88257f40.008053f3-88257f40.00834...@selinc.com>
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>
------------------------------
Subject: Digest Footer
_______________________________________________
This daily digest is from the Framers mailing list
Send messages to [email protected]
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
------------------------------
End of Framers Digest, Vol 7, Issue 22
**************************************
------------------------------
Message: 2
Date: Fri, 22 Jan 2016 03:33:10 +0000
From: Fei Min Lorente <[email protected]>
To: "[email protected]" <[email protected]>
Subject: Re: [Framers] "Modularity" and FrameMaker
Message-ID:
<422cbc2f0af7d24985d811d2e556f3f0b3bc1...@onwater54m.ad.onsemi.com>
Content-Type: text/plain; charset="us-ascii"
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: [email protected]
To: [email protected]
Subject: [Framers] "Modularity" and FrameMaker
Message-ID:
<of3273420e.ef747bf2-on88257f40.008053f3-88257f40.00834...@selinc.com>
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>
------------------------------
Message: 3
Date: Fri, 22 Jan 2016 10:24:26 +0100
From: Yves Barbion <[email protected]>
To: [email protected]
Cc: [email protected]
Subject: Re: [Framers] "Modularity" and FrameMaker
Message-ID:
<CAMa27Ex5VcpO7pshPmNP8PionuUoOKZ-W42y2JgVsWpsQ=i...@mail.gmail.com>
Content-Type: text/plain; charset="utf-8"
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
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.frameusers.com/pipermail/framers_lists.frameusers.com/attachments/20160122/57192e87/attachment-0001.html>
------------------------------
Subject: Digest Footer
_______________________________________________
This daily digest is from the Framers mailing list
Send messages to [email protected]
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
------------------------------
End of Framers Digest, Vol 7, Issue 23
**************************************
_______________________________________________
This message is from the Framers mailing list
Send messages to [email protected]
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
