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
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
docfacto tools & methodology • docfacto tools for developers work from within their IDE and help eliminate documenta<on debt (the amount of work required to ﬁx 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.
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, eﬃciencies 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.
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, diﬀerent output formats or diﬀerent 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.
Documenta<on Debt doc·∙u·∙men·∙ta·∙0on debt: The amount of work required to fix all outstanding documentation issues for a software project.
Beneﬁts 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
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 diﬀerent severity • Required tag op<ons • Checks Classes, Interfaces, Enums, Constructors, Methods and ﬁelds • Adamlets allow for user deﬁned rules
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 eﬀect of code change
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
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 conﬁgura<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
docfacto Taglets – Expose extra informa<on to the user about the why and not just the what
docfacto DITA doclet: Javadoc to DITA • Using the standard Javadoc engine to produce DITA output ﬁles for inclusion with the DITA Open Toolkit • No customisa<on or specialisa<on required
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
XSD2SVG delivers structure from complex XSD formats and outputs in a graphical format XSD2SVG uses XSDTree to create the basic structure ﬁrst
XSD2DITA generates DITA ﬁles for mul< format publishing
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 ﬁles at publish <me
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