Uploaded byDarren Hudson
Docfacto release 2.4
The document provides an overview of docfacto, a company developing tools to help developers and technical authors with documentation. Docfacto tools work within IDEs to link code and documentation, capture designs, and help eliminate documentation debt. The tools include docfacto Adam for checking Javadoc comments against code, docfacto Links for linking code and docs and tracking broken links, and docfacto Beermat for creating diagrams. The goal is to put developers at the core of the documentation process and structure content for reusability.
Docfacto release 2.4
- 1.
- 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.
- 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. 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
- 10. docfacto Adam Eclipse Plugin
- 11. docfacto Adam Eclipse Plugin
- 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. docfacto Links and docfacto Adam in Ac<on
- 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.
- 16.
- 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
- 19. docfacto Taglets Eclipse plugin
- 20. docfacto Taglets Eclipse plugin
- 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
- 24. XSD2DITA generates DITA files for mul< format publishing
- 25.
- 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