1. #NAVUGSummit | #INreno15 #NAVUGSummit SESSION CODE: COM08 AN ELEGANT SOLUTION FOR CREATING DYNAMICS NAV USER DOCUMENTATION Erik Hougaard

2. #NAVUGSummit | #INreno15 NOTES TO THE PRESENTER  Please save this file using the session code and title, e.g., “FIN08 – Best Practices with Year-end Closing”  Slides 2-6 contain notes for the presenter, and are hidden. 2

3. #NAVUGSummit | #INreno15 NOTES TO THE PRESENTER  You may include your picture and company logo on the intro slide only (slide 8).  The “Suggested Sessions” slide (slide 15) is for you to highlight related sessions remaining on the schedule. This is optional; please delete if not used. 3

4. #NAVUGSummit | #INreno15 NOTES TO THE PRESENTER  It is appropriate to provide a brief background (1 minute or less) on your organization.  Attendees love when you submit your slides and reference materials in advance (materials can be included in these slides or separate).  Submit your slides and reference materials by October 1 to events@navug.comevents@navug.com 4

5. #NAVUGSummit | #INreno15  Frame your presentation by answering: – What do you want your audience to learn? – What do you want your audience to do differently? – What result or outcomes do you want your audience to realize?  Clarify your session objectives up front. 5 QUICK BEST PRACTICES

6. #NAVUGSummit | #INreno15  Use more pictures, far less words (7 words on a slide is wonderful).  Alternate communication methods, e.g., polls or videos, to increase attention and interaction. 6 QUICK BEST PRACTICES

7. #NAVUGSummit | #INreno15  Plan and follow a rough agenda, e.g.: – 5 minutes – opening, objectives, intros – 5 minutes – share story – 15 minutes – slides – 20 minutes – demo – 5 minutes – final Q&A – 5 minutes – wrap-up and surveys 7 QUICK BEST PRACTICES

8. #NAVUGSummit | #INreno15 Session objectives:  ? 8 STUMP THE EXPERTS: DEV BEST PRACTICES

9. #NAVUGSummit | #INreno15 9 YOUR PRESENTERS Erik Hougaard R&D Manager E Foqus Microsoft MVP for 2 years

10. #NAVUGSummit | #INreno15 WHAT IS ”HELP” ? Help is several things:  A manual  F1 help  Videos  Single documents  White papers ”help” is what you need to supply your users to be able to use your software.

11. #NAVUGSummit | #INreno15 CHALLENGES OF CREATING ”HELP” First challenge: Documentation is dead the minute you’re finish writing it. Code changes, customers want it work differently, change requests keeps popping up. And the documentation (if any) stays at the initial level.

12. #NAVUGSummit | #INreno15 CHALLENGES OF CREATING ”HELP” Second challenge: Documentation is kept in documents (Word/PDF) sitting on local drives, attached to email, stored on file shares, often in multiple versions without any clear version strategy.

13. #NAVUGSummit | #INreno15 CHALLENGES OF CREATING ”HELP” Third challenge: Customer want F1 help, and this has historical been an nightmare to create with NAV – from compiling CHM files with 3rd party tools to distribute files to clients. Anyone still got nightmares over “RoboHelp” ?

14. #NAVUGSummit | #INreno15 CHALLENGES OF CREATING ”HELP” Fourth challenge: New formats comes along all the time, creating an eBook with your help content would be a very modern thing to do.

15. #NAVUGSummit | #INreno15  Separate tasks into: – Writing – Designing – Producing  Work with source code management (code and documentation goes together)  Put documentation into build environment 15 GOALS

16. #NAVUGSummit | #INreno15 FIRST STEP – ORGANIZE THE INPUT TEXT Help text can either be content specific (help to a specific field) or general. With NAV the requirement for content specific help is mandatory, users can press F1 and expects to get content specific help.

17. #NAVUGSummit | #INreno15  We have created two tables in NAV – one for holding content specific help and one for holding general help. The content specific table can be pre-populated with references to all objects and fields.  So now, we have a organized database for our text. We created BLOB fields to hold the text. This will almost solve the 2nd problem – Putting the text in a database. We can reference object versions, languages etc. 17 FIRST STEP – ORGANIZE THE INPUT TEXT

18. #NAVUGSummit | #INreno15 What ”syntax” should we use for writing and storing our help text ?  Word ?  HTML ?  SGML ?  TXT ? 18 ”PORTABLE” TEXT – WHAT TO WRITE ?

19. #NAVUGSummit | #INreno15 THE ANSWER IS MARKDOWN  Readable formatted text

20. #NAVUGSummit | #INreno15  For the Help Server we need text in HTML  For a manual we need some sort of formattet text  For an eBook we need something eBook specific 20 WHAT ”OUTPUT” FORMATS DO WE NEED?

21. #NAVUGSummit | #INreno15 PANDOC – WWW.PANDOC.ORG  About pandoc  If you need to convert files from one markup format into another, pandoc is your swiss-army knife. Pandoc can convert documents in markdown, reStructuredText, textile, HTML, DocBook, LaTeX, MediaWiki markup, TWiki markup, OPML, Emacs Org-Mode, Txt2Tags, Microsoft Word docx, EPUB, or Haddock markup tomarkdownreStructuredTexttextileHTMLDocBookLaTeXMediaWiki markupTWiki markupOPML Org-ModeTxt2TagsdocxEPUBHaddock markup  HTML formats: XHTML, HTML5, and HTML slide shows using Slidy, reveal.js, Slideous, S5, or DZSlides.Slidyreveal.jsSlideousS5DZSlides  Word processor formats: Microsoft Word docx, OpenOffice/LibreOffice ODT, OpenDocument XMLdocxODTOpenDocument XML  Ebooks: EPUB version 2 or 3, FictionBook2EPUBFictionBook2  Documentation formats: DocBook, GNU TexInfo, Groff man pages, Haddock markupDocBookGNU TexInfoGroff manHaddock markup  Page layout formats: InDesign ICMLInDesign ICML  Outline formats: OPMLOPML  TeX formats: LaTeX, ConTeXt, LaTeX Beamer slidesLaTeXConTeXt  PDF via LaTeX PDF  Lightweight markup formats: Markdown (including CommonMark), reStructuredText, AsciiDoc, MediaWiki markup, DokuWiki markup, Emacs Org-Mode, TextileMarkdownCommonMarkreStructuredTextAsciiDocMediaWiki markupDokuWiki markupOrg-ModeTextile  Custom formats: custom writers can be written in lua.lua

22. #NAVUGSummit | #INreno15 22 LATEX FOR BOOKS

23. #NAVUGSummit | #INreno15 23 LATEX FOR BOOKS

24. #NAVUGSummit | #INreno15 GETTING STRUCTURE INTO OUR DOCUMENTATION A good technical books has a table of content, so we will create our own ToC. And when we look closer at the Dynamics Help Server we find a ToC.xml file that hold the information for the left side menu.

25. #NAVUGSummit | #INreno15 A XML file that hold the Table of Content and points to objects and articles. 25 STRUCTURE

26. #NAVUGSummit | #INreno15 GRAPHICAL LAYOUT Both for the Help Server and for a PDF manual, we need:

27. #NAVUGSummit | #INreno15  Quite simple, a template HTML file with place holders for titles and texts. 27 HELP SERVER LAYOUT

28. #NAVUGSummit | #INreno15 Jigsaw of LaTeX snippes for:  ManualStart  ManualEnd  ChapterHead  ChapterBetweenTopics  TableTopicHead And many more….. Look in template.xml 28 MANUAL LAYOUT

29. #NAVUGSummit | #INreno15 EDITING AND STORING HELP TEXT WITH NAV CODE

30. #NAVUGSummit | #INreno15 EDITING AND STORING HELP TEXT WITH NAV CODE

31. #NAVUGSummit | #INreno15 EDITING AND STORING HELP TEXT WITH NAV CODE

32. #NAVUGSummit | #INreno15 EDITING AND STORING HELP TEXT WITH NAV CODE

33. #NAVUGSummit | #INreno15 EDITING AND STORING HELP TEXT WITH NAV CODE

34. #NAVUGSummit | #INreno15 RUNNING THE WHOLE THING

35. #NAVUGSummit | #INreno15 35 SUCCESS – HELP SERVER

36. #NAVUGSummit | #INreno15 36 SUCCESS – PDF MANUAL

37. #NAVUGSummit | #INreno15 37 AUTOMATED BUILDS

38. #NAVUGSummit | #INreno15  My blog: www.hougaard.comwww.hougaard.com  GitHub: https://github.com/hougaard/HelpToolshttps://github.com/hougaard/HelpTools 38 WHERE TO FIND ALL THIS:

39. #NAVUGSummit | #INreno15 ?? 39 AGENDA

40. #NAVUGSummit | #INreno15 40 Q&A

41. #NAVUGSummit | #INreno15 CODE EXAMPLE Use Consolas font for inserting example code.

42. #NAVUGSummit | #INreno15 23 tips and tricks for developers Fri, 10:30 Huddle up: IT Fri, 2:15 42 SUGGESTED SESSIONS

43. #NAVUGSummit | #INreno15  Erik Hougaard – erik@hougaard.com 43 CONTACT INFO

44. #NAVUGSummit | #INreno15 THANK YOU! Complete your survey now! Download these slides from navug.com Ask questions and connect in the Summit 2015 community Submit your town hall questions to townhall@navug.comtownhall@navug.com Visit the I Love NAV booth #233 – Wed 6:00 – 8:00 – Thu 12:00 – 2:00 – Fri 10:00 – 12:00 Visit the NAVUG Medics in the ABC Computers Hub Have fun! 44