#navugsummit | #inreno15 #navugsummit session code: com08 an elegant solution for creating dynamics...
TRANSCRIPT
#NAVUGSummit | #INreno15
#NAVUGSummit
SESSION CODE: COM08AN ELEGANT SOLUTION FOR CREATING DYNAMICS
NAV USER DOCUMENTATION
Erik Hougaard
#NAVUGSummit | #INreno15 9
YOUR PRESENTERS
Erik HougaardR&D ManagerE FoqusMicrosoft MVP for 2 years
#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.
#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.
#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.
#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” ?
#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.
#NAVUGSummit | #INreno15 15
Separate tasks into:– Writing– Designing– Producing
Work with source code management (code and documentation goes together)
Put documentation into build environment
GOALS
#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.
#NAVUGSummit | #INreno15 17
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.
FIRST STEP – ORGANIZE THE INPUT TEXT
#NAVUGSummit | #INreno15 18
What ”syntax” should we use for writing and storing our help text ?
Word ? HTML ? SGML ? TXT ?
”PORTABLE” TEXT – WHAT TO WRITE ?
#NAVUGSummit | #INreno15
THE ANSWER IS MARKDOWN
Readable formatted text
#NAVUGSummit | #INreno15 20
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
WHAT ”OUTPUT” FORMATS DO WE NEED?
#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 to
HTML formats: XHTML, HTML5, and HTML slide shows using Slidy, reveal.js, Slideous, S5, or DZSlides.
Word processor formats: Microsoft Word docx, OpenOffice/LibreOffice ODT, OpenDocument XML Ebooks: EPUB version 2 or 3, FictionBook2 Documentation formats: DocBook, GNU TexInfo, Groff man pages, Haddock markup Page layout formats: InDesign ICML Outline formats: OPML TeX formats: LaTeX, ConTeXt, LaTeX Beamer slides PDF via LaTeX Lightweight markup formats: Markdown (including CommonMark), reStructuredText, AsciiDoc,
MediaWiki markup, DokuWiki markup, Emacs Org-Mode, Textile Custom formats: custom writers can be written in lua.
#NAVUGSummit | #INreno15 22
LATEX FOR BOOKS
#NAVUGSummit | #INreno15 23
LATEX FOR BOOKS
#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.
#NAVUGSummit | #INreno15 25
A XML file that hold the Table of Content and points to objects and articles.
STRUCTURE
#NAVUGSummit | #INreno15
GRAPHICAL LAYOUT
Both for the Help Server and for a PDF manual, we need:
Layout
#NAVUGSummit | #INreno15 27
Quite simple, a template HTML file with place holders for titles and texts.
HELP SERVER LAYOUT
#NAVUGSummit | #INreno15 28
Jigsaw of LaTeX snippes for: ManualStart ManualEnd ChapterHead ChapterBetweenTopics TableTopicHeadAnd many more….. Look in template.xml
MANUAL LAYOUT
#NAVUGSummit | #INreno15
EDITING AND STORING HELP TEXT WITH NAV CODE
#NAVUGSummit | #INreno15
EDITING AND STORING HELP TEXT WITH NAV CODE
#NAVUGSummit | #INreno15
EDITING AND STORING HELP TEXT WITH NAV CODE
#NAVUGSummit | #INreno15
EDITING AND STORING HELP TEXT WITH NAV CODE
#NAVUGSummit | #INreno15
EDITING AND STORING HELP TEXT WITH NAV CODE
#NAVUGSummit | #INreno15
RUNNING THE WHOLE THING
#NAVUGSummit | #INreno15 35
SUCCESS – HELP SERVER
#NAVUGSummit | #INreno15 36
SUCCESS – PDF MANUAL
#NAVUGSummit | #INreno15 37
AUTOMATED BUILDS
#NAVUGSummit | #INreno15 38
My blog: www.hougaard.com
GitHub: https://github.com/hougaard/HelpTools
WHERE TO FIND ALL THIS:
#NAVUGSummit | #INreno15 40
Q&A
#NAVUGSummit | #INreno15 42
• 23 tips and tricks for developers
Fri, 10:30
• Huddle up: ITFri, 2:15
SUGGESTED SESSIONS
#NAVUGSummit | #INreno15 44
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 [email protected]
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!
