#navugsummit | #inreno15 #navugsummit session code: com08 an elegant solution for creating dynamics...

#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 43

Erik Hougaard– erik@hougaard.com

CONTACT INFO

#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 townhall@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!