Fwd: Re: [dita-users] SME information providers using DITA

[Ron Wheeler]

This was posted in the DITA users forum.
Sounds like a pretty nice setup for managing software documentation and
marketing materials..

I use DITA and topic-based authoring for manuals and for analysis
reports for clients.
It does help a lot.

The difficulty of using topic-based authoring in the wiki (as well as
people not thinking in topics) is the cause of a lot of the problems
that we now are addressing (outdated material, redundant text, pages
that are confusing mind-dumps, difficulty in connecting software
activity to document production, very little documentation of
specifications, etc.) and they will re-occur as long as we depend on
static web pages and the wiki.

I like DITA's use of XML but I am used to working with XML.
I like the fact that ASCIIDoc supports "include" which should make it
easier to transition to a topic-based architecture.
Not sure about the editing codes and how well it separates content from
styling and how the fragments can be re-used.

Being able to generate documents on the fly from fragments stored in a
repository with source control and versioning would be great.


Ron


-------- Forwarded Message --------



Hello Ant,

PMC-Sierra is not an "organization" in the sense that you are seeking,
so I'll limit my answer to what I'd tell your CEO.

In globally distributed company of ~1600, sporting approx. 1000
engineers of various types, with a heavily documentation-driven ISO9000
hardware/software development process, we have exactly 3 full time tech
writers, two part time contractors, a manager, and a tools guy (me).

We use topic-based architecture to collaborate on huge documents across
offices, teams, and time zones.

We use flagging and filtering to reuse content heavily between product
variants and tighten up the review cycle.

We use specializations to allow developers to generate code right off
their documentation.

We use multichannel delivery to push content where ever it needs to be:
firmware, desktop help, web help, knowledgebase, pdf, whatever. Whatever
anyone wants next, we'll do it.

We use programmatic diffing tools to create authoritative
representations of the differences between documents; we do not need to
trust anyone "turn on tracked changes". We can always determine
*exactly* what has changed and who changed it.

We never, ever, lose the source or have any doubt about which version of
the source was used to create the content that the customer has in their
hands.

On top of all that, and on the shallower side of the scale, we've honed
our publishing scripts to the point where the marketing department
thought we'd outsourced our design work; our documentation is gorgeous.
Our DITA-sourced docs make Word or Framemaker sourced documentation look
positively shabby by comparison.

None of this (NONE of this) has been easy or smooth and has been a
learning experience that has stretched across years, but it would be
impossible with any other toolset.

Cheers,
Jeff.

On Fri, Jan 23, 2015 at 7:15 AM, [hidden email]
<mailto:[hidden email]> [dita-users] <[hidden email]
<mailto:[hidden email]>> wrote:

    Ideally UK or European...

    Can anybody tell me which organisations are using topic-based,
    structured authoring to deliver information developed by SMEs to
    their audiences?  Of particular interest are standards organisations
    and professional organisations for engineering and other sciences.

    I have to justify to my CEO why we should adopt this approach, and
    need examples.

    Many thanks,

    Ant




__._,_.___
------------------------------------------------------------------------
Posted by: Jeff Hooker <[hidden email]>
------------------------------------------------------------------------


Visit Your Group
<https://groups.yahoo.com/neo/groups/dita-users/info;_ylc=X3oDMTJmMmhlcG8xBF9TAzk3MzU5NzE0BGdycElkAzEyNzQ0MjA5BGdycHNwSWQDMTcwNjAzMDM5MARzZWMDdnRsBHNsawN2Z2hwBHN0aW1lAzE0MjIwMzAwMzc->


  * New Members
    <https://groups.yahoo.com/neo/groups/dita-users/members/all;_ylc=X3oDMTJnYzhnMW05BF9TAzk3MzU5NzE0BGdycElkAzEyNzQ0MjA5BGdycHNwSWQDMTcwNjAzMDM5MARzZWMDdnRsBHNsawN2bWJycwRzdGltZQMxNDIyMDMwMDM3>
    4

Yahoo! Groups
<https://groups.yahoo.com/neo;_ylc=X3oDMTJlcWE1bWcwBF9TAzk3NDc2NTkwBGdycElkAzEyNzQ0MjA5BGdycHNwSWQDMTcwNjAzMDM5MARzZWMDZnRyBHNsawNnZnAEc3RpbWUDMTQyMjAzMDAzNw-->

• Privacy <https://info.yahoo.com/privacy/us/yahoo/groups/details.html>
• Unsubscribe
<mailto:[hidden email]?subject=Unsubscribe> •
Terms of Use <https://info.yahoo.com/legal/us/yahoo/utos/terms/>

__,_._,___

[Jacques Le Roux]

Le 23/01/2015 17:44, Ron Wheeler a écrit :

> This was posted in the DITA users forum.
> Sounds like a pretty nice setup for managing software documentation and marketing materials..
>
> I use DITA and topic-based authoring for manuals and for analysis reports for clients.
> It does help a lot.
>
> The difficulty of using topic-based authoring in the wiki (as well as people not thinking in topics) is the cause of a lot of the problems that we
> now are addressing (outdated material, redundant text, pages that are confusing mind-dumps, difficulty in connecting software activity to document
> production, very little documentation of specifications, etc.) and they will re-occur as long as we depend on static web pages and the wiki.
>
> I like DITA's use of XML but I am used to working with XML.
> I like the fact that ASCIIDoc supports "include" which should make it easier to transition to a topic-based architecture.
> Not sure about the editing codes and how well it separates content from styling and how the fragments can be re-used.
>
> Being able to generate documents on the fly from fragments stored in a repository with source control and versioning would be great.

+1

Jacques

>
>
> Ron
>
>
> -------- Forwarded Message --------
>
>
>
> Hello Ant,
>
> PMC-Sierra is not an "organization" in the sense that you are seeking, so I'll limit my answer to what I'd tell your CEO.
>
> In globally distributed company of ~1600, sporting approx. 1000 engineers of various types, with a heavily documentation-driven ISO9000
> hardware/software development process, we have exactly 3 full time tech writers, two part time contractors, a manager, and a tools guy (me).
>
> We use topic-based architecture to collaborate on huge documents across offices, teams, and time zones.
>
> We use flagging and filtering to reuse content heavily between product variants and tighten up the review cycle.
>
> We use specializations to allow developers to generate code right off their documentation.
>
> We use multichannel delivery to push content where ever it needs to be: firmware, desktop help, web help, knowledgebase, pdf, whatever. Whatever
> anyone wants next, we'll do it.
>
> We use programmatic diffing tools to create authoritative representations of the differences between documents; we do not need to trust anyone "turn
> on tracked changes". We can always determine *exactly* what has changed and who changed it.
>
> We never, ever, lose the source or have any doubt about which version of the source was used to create the content that the customer has in their
> hands.
>
> On top of all that, and on the shallower side of the scale, we've honed our publishing scripts to the point where the marketing department thought
> we'd outsourced our design work; our documentation is gorgeous. Our DITA-sourced docs make Word or Framemaker sourced documentation look positively
> shabby by comparison.
>
> None of this (NONE of this) has been easy or smooth and has been a learning experience that has stretched across years, but it would be impossible
> with any other toolset.
>
> Cheers,
> Jeff.
>
> On Fri, Jan 23, 2015 at 7:15 AM, [hidden email] <mailto:[hidden email]> [dita-users] <[hidden email]
> <mailto:[hidden email]>> wrote:
>
>    Ideally UK or European...
>
>    Can anybody tell me which organisations are using topic-based,
>    structured authoring to deliver information developed by SMEs to
>    their audiences?  Of particular interest are standards organisations
>    and professional organisations for engineering and other sciences.
>
>    I have to justify to my CEO why we should adopt this approach, and
>    need examples.
>
>    Many thanks,
>
>    Ant
>
>
>
>
> __._,_.___
> ------------------------------------------------------------------------
> Posted by: Jeff Hooker <[hidden email]>
> ------------------------------------------------------------------------
>
>
> Visit Your Group
> <https://groups.yahoo.com/neo/groups/dita-users/info;_ylc=X3oDMTJmMmhlcG8xBF9TAzk3MzU5NzE0BGdycElkAzEyNzQ0MjA5BGdycHNwSWQDMTcwNjAzMDM5MARzZWMDdnRsBHNsawN2Z2hwBHN0aW1lAzE0MjIwMzAwMzc->
>
>
>  * New Members
> <https://groups.yahoo.com/neo/groups/dita-users/members/all;_ylc=X3oDMTJnYzhnMW05BF9TAzk3MzU5NzE0BGdycElkAzEyNzQ0MjA5BGdycHNwSWQDMTcwNjAzMDM5MARzZWMDdnRsBHNsawN2bWJycwRzdGltZQMxNDIyMDMwMDM3>
>    4
>
> Yahoo! Groups
> <https://groups.yahoo.com/neo;_ylc=X3oDMTJlcWE1bWcwBF9TAzk3NDc2NTkwBGdycElkAzEyNzQ0MjA5BGdycHNwSWQDMTcwNjAzMDM5MARzZWMDZnRyBHNsawNnZnAEc3RpbWUDMTQyMjAzMDAzNw-->
>
> • Privacy <https://info.yahoo.com/privacy/us/yahoo/groups/details.html> • Unsubscribe
> <mailto:[hidden email]?subject=Unsubscribe> • Terms of Use <https://info.yahoo.com/legal/us/yahoo/utos/terms/>
>
> __,_._,___
>
>
>