docfacto	  Overview	  Release	  2.4	  
docfacto	  docfacto	  is	  developing	  cool	  tools	  for	  developers	  	  that	  take	  the	  “too	  hard”	  out	  of	 ...
docfacto	  introduc<on	  ü Developers	  should	  be	  core	  to	  the	  documenta0on	  process	  ü The	  code	  should	 ...
docfacto	  tools	  &	  methodology	  •  docfacto	  tools	  for	  developers	  work	  from	  within	  their	  IDE	  and	  h...
docfacto:	  elimina<ng	  documenta<on	  debt	  •  docfacto	  tools	  make	  understanding	  the	  level	  of	  documenta<o...
docfacto	  &	  structured	  content	  •  At	  docfacto,	  we	  understand	  that	  crea<ng	  reusable,	  structured	  cont...
Documenta<on	  Debt	  doc·∙u·∙men·∙ta·∙0on	  	  debt:	   The amount of work required to fix all outstanding documentation ...
Benefits	  of	  good	  documenta<on	  •  Reduced	  complexity	  with	  integrated	  toolset	  –  Reduced	  licensing	  cost...
docfacto	  Adam	  checks	  the	  correctness	  of	  Javadoc	  against	  the	  code	  and	  is	  a	  vital	  tool	  for	  m...
docfacto	  Adam	  Eclipse	  Plugin	  
docfacto	  Adam	  Eclipse	  Plugin	  
docfacto	  Links	  •  The	  ability	  to	  link	  code	  to	  documenta<on	  and	  documenta<on	  to	  code.	  •  Eclipse	...
docfacto	  Links	  and	  docfacto	  Adam	  in	  Ac<on	  
docfacto	  Beermat	  •  Graphical	  tool	  to	  help	  create	  simple	  diagrams	  within	  eclipse	  •  Capture	  fee	  ...
docfacto	  Beermat	  Sample	  
docfacto	  Beermat	  Sample	  
docfacto	  Taglets	  are	  a	  way	  of	  inser<ng	  extra	  user	  and	  system	  documenta<on	  into	  the	  code	  and	...
docfacto	  Taglets	  –	  Expose	  extra	  informa<on	  to	  the	  user	  about	  the	  why	  and	  not	  just	  the	  what...
docfacto	  Taglets	  Eclipse	  plugin	  
docfacto	  Taglets	  Eclipse	  plugin	  
docfacto	  DITA	  doclet:	  Javadoc	  to	  DITA	  •  Using	  the	  standard	  Javadoc	  engine	  to	  produce	  DITA	  out...
XSDTree	  API	  allows	  you	  to	  capture	  the	  annota<ons	  with	  the	  XSD	  document	  allowing	  produc<on	  of	 ...
XSD2SVG	  delivers	  structure	  from	  complex	  XSD	  formats	  and	  outputs	  in	  a	  graphical	  format	  XSD2SVG	  ...
XSD2DITA	  generates	  DITA	  files	  for	  mul<	  format	  publishing	  
Future	  Developments	  
DITA	  aware	  editor	  •  DITA	  aware	  editor	  for	  Eclipse	  IDE	  –  Make	  customisa<ons	  and	  specialisa<ons	  ...
Screen	  Capture	  facility	  •  Screen	  Capture	  Eclipse	  plugin	  •  Ability	  to	  embed	  in	  SVG	  •  Annota<on	 ...
Upcoming SlideShare
Loading in …5
×

Docfacto release 2.4

576 views

Published on

docfacto release 2.4 presentation

Published in: Technology, Business
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
576
On SlideShare
0
From Embeds
0
Number of Embeds
3
Actions
Shares
0
Downloads
0
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Docfacto release 2.4

  1. 1. docfacto  Overview  Release  2.4  
  2. 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. 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. 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. 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. 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.    
  7. 7. Documenta<on  Debt  doc·∙u·∙men·∙ta·∙0on    debt:   The amount of work required to fix all outstanding documentation issues for a software project.
  8. 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. 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  
  10. 10. docfacto  Adam  Eclipse  Plugin  
  11. 11. docfacto  Adam  Eclipse  Plugin  
  12. 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  
  13. 13. docfacto  Links  and  docfacto  Adam  in  Ac<on  
  14. 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  
  15. 15. docfacto  Beermat  Sample  
  16. 16. docfacto  Beermat  Sample  
  17. 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. 18. docfacto  Taglets  –  Expose  extra  informa<on  to  the  user  about  the  why  and  not  just  the  what  
  19. 19. docfacto  Taglets  Eclipse  plugin  
  20. 20. docfacto  Taglets  Eclipse  plugin  
  21. 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. 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. 23. XSD2SVG  delivers  structure  from  complex  XSD  formats  and  outputs  in  a  graphical  format  XSD2SVG  uses  XSDTree  to  create  the  basic  structure  first  
  24. 24. XSD2DITA  generates  DITA  files  for  mul<  format  publishing  
  25. 25. Future  Developments  
  26. 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. 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  

×