2. docfacto
docfacto
is
developing
cool
tools
for
developers
that
take
the
“too
hard”
out
of
documenta0on,
assis<ng
technical
authors
with
content
and
helping
businesses
eliminate
documenta0on
debt
3. docfacto
introduc<on
ü Developers
should
be
core
to
the
documenta0on
process
ü The
code
should
be
the
source
of
the
truth
ü The
code
should
be
linked
to
the
documenta0on
ü The
code
should
explain
the
why
ü Developers
should
be
crea<ng
the
content
for
technical
authors
to
do
what
they
do
best:
authoring
ü Structured
content
is
the
best
way
to
create
and
re-‐use
documenta<on
4. docfacto
tools
&
methodology
• docfacto
tools
for
developers
work
from
within
their
IDE
and
help
eliminate
documenta<on
debt
(the
amount
of
work
required
to
fix
all
outstanding
documenta<on
issues
for
a
soKware
project)
• Together
our
tools
make
it
easier
for
developers
to
increase
the
accuracy
of
code
comments,
capture
white
board
designs,
and
write
user
or
system
documenta<on.
• The
code
can
then
be
linked
to
the
documenta<on
to
keep
both
in
sync.
• This
methodology
puts
the
soKware
team
at
the
heart
of
the
documenta<on
process
ensuring
the
code
is
the
source
of
the
truth.
• This
way
the
developers
are
crea<ng
the
content
that
technical
authors
need
for
authoring.
5. docfacto:
elimina<ng
documenta<on
debt
• docfacto
tools
make
understanding
the
level
of
documenta<on
debt
and
the
impact
of
code
change
easier.
• docfacto
tools
used
in
conjunc<on
with
our
methodology
helps
eliminate
documenta<on
debt,
which
will
improve
performance,
efficiencies
and
lower
the
barriers
to
developers
completely
and
accurately
commen<ng
code.
• The
best
way
for
a
developer
to
demonstrate
the
brilliance
of
their
code
is
to
capture
all
the
smart
thinking
that
went
into
it.
When
the
developer’s
clever
logic
isn’t
captured
nobody
ever
knows
if
the
code
is
good
or
“why”
it
was
done
the
way
it
is.
• Capturing
these
ideas
leads
to
beSer
documenta<on.
Ul<mately,
soKware
is
only
as
good
as
its
suppor<ng
documenta<on.
Not
documen<ng
code
creates
legacy
code
as
soon
as
it’s
wriSen
and
this
is
bad
for
business.
6. docfacto
&
structured
content
• At
docfacto,
we
understand
that
crea<ng
reusable,
structured
content
is
key
for
good
technical
documenta<on.
• We
work
with
DITA,
because
it’s
a
great
way
to
manage
single-‐
source
documenta<on
for
product
variants,
different
output
formats
or
different
languages.
• DITA
can
be
complex,
and
we
think
it
should
be
easier
so
that
it’s
suitable
for
developers
to
use
on
projects
of
any
size.
8. Benefits
of
good
documenta<on
• Reduced
complexity
with
integrated
toolset
– Reduced
licensing
cost
• Increased
community
uptake
• Improved
understanding
of
the
system
/
applica<on
• Reduced
support
calls
• Improved
code
reuse
• Faster
developer
on-‐boarding
• Improved
maintainability
• Driving
XML
Standards
• Improved
intellectual
property
value
• Reduced
transla<on
costs
• Dynamically
link
between
code
and
documenta<on
• Enforcing
the
code
documenta<on
standard
9. docfacto
Adam
checks
the
correctness
of
Javadoc
against
the
code
and
is
a
vital
tool
for
managing
the
comments
built
into
the
code
• Javadoc
doesn’t
issue
warnings
about
incorrect
comments
– Classes
/
methods
oKen
get
refactored,
leaving
the
old
comments
in
place
• docfacto
Adam
guarantees
consistency
by
enforcing
comment
coding
standards
• Over
24
rules
baked
in,
each
rule
can
have
a
different
severity
• Required
tag
op<ons
• Checks
Classes,
Interfaces,
Enums,
Constructors,
Methods
and
fields
• Adamlets
allow
for
user
defined
rules
12. docfacto
Links
• The
ability
to
link
code
to
documenta<on
and
documenta<on
to
code.
• Eclipse
plugin
for
ease
of
use.
• Reports
generated
on
broken
links
or
links
that
are
out
of
date
• Gives
the
ability
to
see
the
documenta<on
coverage
• Also
shows
the
documenta<on
effect
of
code
change
14. docfacto
Beermat
• Graphical
tool
to
help
create
simple
diagrams
within
eclipse
• Capture
fee
hand
diagrams,
white
board
approach
• Diagrams
in
SVG
for
simple
transla<on
• Diagrams
can
be
linked
to
code
• Flow
/
UML
diagrams
can
be
created
17. docfacto
Taglets
are
a
way
of
inser<ng
extra
user
and
system
documenta<on
into
the
code
and
provide
a
high
level
of
visual
clarity
• Simple
configura<on
allows
for
the
genera<on
of
either
user
documenta<on
with
notes,
or
system
documenta<on.
• Important
informa<on
can
be
made
to
standout
within
the
Javadoc
• The
Example
Taglet
retrieves
code
from
the
compiled
code
space
and
is
injected
during
the
Javadoc
process.
– This
removes
the
requirement
to
include
code
samples
in
comments
which
do
not
get
refactored.
• docfacto
Taglets
include
– Note,
System,
ToDo,
Example,
Media
• All
Taglets
can
generate
HTML
or
DITA
18. docfacto
Taglets
–
Expose
extra
informa<on
to
the
user
about
the
why
and
not
just
the
what
21. docfacto
DITA
doclet:
Javadoc
to
DITA
• Using
the
standard
Javadoc
engine
to
produce
DITA
output
files
for
inclusion
with
the
DITA
Open
Toolkit
• No
customisa<on
or
specialisa<on
required
22. XSDTree
API
allows
you
to
capture
the
annota<ons
with
the
XSD
document
allowing
produc<on
of
…
– XSD2DITA
which
allows
you
to
generate
Reference
Topic
Files
from
the
XSD
– XSD2SVG
which
allows
you
diagramma<cally
show
the
hierarchical
nature
of
the
required
XML
– Use
the
API
to
generate
any
output
required
23. XSD2SVG
delivers
structure
from
complex
XSD
formats
and
outputs
in
a
graphical
format
XSD2SVG
uses
XSDTree
to
create
the
basic
structure
first
26. DITA
aware
editor
• DITA
aware
editor
for
Eclipse
IDE
– Make
customisa<ons
and
specialisa<ons
simple
– Syntax
diagram
wizard
– DITA
map
editor
(with
link
resolu<on)
– DITAVAL
editor
– Simple
launching
of
publica<on
targets
– Cut
and
Paste
with
normalisa<on
– Auto
word
sense
and
tag
wrap
– Keyref
mapper
– DITA
extensions
to
be
able
to
include
code
samples
and
snippets
from
files
at
publish
<me
27. Screen
Capture
facility
• Screen
Capture
Eclipse
plugin
• Ability
to
embed
in
SVG
• Annota<on
via
Beermat
or
Grabit
• Time
delayed
capture
• Mul<
screen
func<onality
