#NAVUGSummit

SESSION CODE: COM08

AN ELEGANT SOLUTION FOR CREATING DYNAMICS
NAV USER DOCUMENTATION

Erik Hougaard
#NAVUGSummit | #INreno15

YOUR PRESENTERS

Erik
Hougaard
R&D
Manager
E Foqus
Microsoft
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 youre 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

GOALS

Separate tasks into:

Writing

Designing

Producing

Work with source code management (code

and documentation goes together)

Put documentation into build environment

#NAVUGSummit | #INreno15

15

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

FIRST STEP ORGANIZE THE INPUT TEXT

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.

#NAVUGSummit | #INreno15

17

PORTABLE TEXT WHAT TO WRITE ?

What syntax should we use for writing and
storing our help text ?

Word ?

HTML ?

SGML ?

TXT ?
#NAVUGSummit | #INreno15

18

THE ANSWER IS MARKDOWN

Readable
formatted text

#NAVUGSummit | #INreno15

WHAT OUTPUT FORMATS DO WE NEED?

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

#NAVUGSummit | #INreno15

20

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

LATEX FOR BOOKS

#NAVUGSummit | #INreno15

22

LATEX FOR BOOKS

#NAVUGSummit | #INreno15

23

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

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

25

GRAPHICAL LAYOUT
Both for the Help Server and for a PDF
manual, we need:

Layout
#NAVUGSummit | #INreno15

HELP SERVER LAYOUT

Quite simple, a template HTML file with

place holders for titles and texts.

#NAVUGSummit | #INreno15

27

MANUAL LAYOUT
Jigsaw of LaTeX snippes for:

ManualStart

ManualEnd

ChapterHead

ChapterBetweenTopics

TableTopicHead

And many more.. Look in template.xml

#NAVUGSummit | #INreno15

28

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

SUCCESS HELP SERVER

#NAVUGSummit | #INreno15

35

SUCCESS PDF MANUAL

#NAVUGSummit | #INreno15

36

AUTOMATED BUILDS

#NAVUGSummit | #INreno15

37

WHERE TO FIND ALL THIS:

My blog: www.hougaard.com

GitHub: https://
github.com/hougaard/HelpTools

#NAVUGSummit | #INreno15

38

Q&A
#NAVUGSummit | #INreno15

40

SUGGESTED SESSIONS
23 tips and tricks for
Fri, 10:30
developers
Fri, 2:15

#NAVUGSummit | #INreno15

Huddle up: IT

42

CONTACT INFO

Erik Hougaard

erik@hougaard.com

#NAVUGSummit | #INreno15

43

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

#NAVUGSummit | #INreno15

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