design of your documentation universe - madcap...
TRANSCRIPT
![Page 2: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/2.jpg)
![Page 3: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/3.jpg)
• Design of your documentation universe
WHAT IS THIS ABOUT?
![Page 4: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/4.jpg)
WHAT IS THIS ABOUT?
• Design of your documentation universe
• Available options
• Pros and cons
• What we do… in the world’s oldest living Flare project
• One size does not fit all
• It’s a living thing, not static
![Page 5: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/5.jpg)
DETAILS IN THE ONLINE HELP AND PDF
![Page 6: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/6.jpg)
External Architecture
![Page 7: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/7.jpg)
WHAT I’M COVERING IN THIS SESSION
• Flare Project Structures
• Source Control
• Where to Store Projects
• Task and Project Management
• Topic Reviews
• Templates
• Importing External Files
• Global Dictionaries
• Multimedia
• Analysis, Reporting, and Feedback
• Publishing Output
Things not covered in
this session are
discussed in detail in
the online Help.
![Page 8: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/8.jpg)
FLARE PROJECT STRUCTURES
• How many Flare projects do I create?
• How should they relate to each other, if at all?
![Page 9: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/9.jpg)
SINGLE PROJECT
![Page 10: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/10.jpg)
PROS CONS
Simple, less coordination &
management
Not good if you have multiple writers
and no source control
Put everything in one project Extremely large project can become
unwieldy
![Page 11: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/11.jpg)
MULTIPLE PROJECTS – NO RELATIONSHIP
![Page 12: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/12.jpg)
PROS CONS
Still simple Not good if you have multiple writers on
same project and no source control
Lets multiple authors work on
independent projects without conflicts
If projects need to share some things
(e.g., stylesheet), this isn’t the solution
Breaking into smaller projects can
improve performance
![Page 13: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/13.jpg)
MULTIPLE PROJECTS – GLOBAL PROJECT LINKING
Option 1
![Page 14: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/14.jpg)
MULTIPLE PROJECTS – GLOBAL PROJECT LINKING
Option 2
![Page 15: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/15.jpg)
MULTIPLE PROJECTS – GLOBAL PROJECT LINKING
Option 3
![Page 16: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/16.jpg)
PROS CONS
Single-sourcing across projects Beware of the threshold
Multiple authors leverage common files Beware of the domino effect
(GPL works best for certain kinds and
numbers of files)
Manual or automatic imports
Import in various ways (e.g., file name,
file type, conditions)
![Page 17: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/17.jpg)
MULTIPLE PROJECTS – MERGING PROJECTS
![Page 18: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/18.jpg)
PROS CONS
Simple to set up Must have access to child projects or
output
Multiple authors work independently,
but you leverage their content
Links between projects takes extra
effort
Working in different projects can help
prevent conflicts
Doesn’t solve need to share certain
files (e.g., stylesheets)
HTML5 Side/Top Nav don’t support
runtime merging
Synonyms are separate in each project
![Page 19: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/19.jpg)
MULTIPLE PROJECTS – MULTILINGUAL OUTPUT
![Page 20: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/20.jpg)
PROS CONS
Simple to set up File names need to be the same in
each project
Convenient structure when you have
multiple translators
Flare user must have recent version of
Lingo installed
Online and print outputs both
supported
![Page 21: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/21.jpg)
COMBINATION OF DIFFERENT STRUCTURES
Example 1:
- GPL
- Merging
![Page 22: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/22.jpg)
COMBINATION OF DIFFERENT STRUCTURES
Example 2:
- Merging
- Multilingual
![Page 23: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/23.jpg)
WHAT WE DO
![Page 24: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/24.jpg)
WHAT WE DO – MORE SPECIFICALLY
![Page 25: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/25.jpg)
SOURCE CONTROL
• Local copy of project mapped
to another copy on a server
• Many source control tools
available
– Microsoft TFS, Git, Perforce,
Subversion, etc.
– MadCap Central allows for
single-bound and dual-bound
models with Git behind the
scenes
![Page 26: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/26.jpg)
SOURCE CONTROL
![Page 27: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/27.jpg)
SOURCE CONTROL
![Page 28: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/28.jpg)
SOURCE CONTROL
• Branching
– Work on different
versions of the same
project
– Good for agile
development
![Page 29: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/29.jpg)
PROS CONS
Efficient way for multiple writers to work
on same project; resolve conflicts
Setup can be challenging for some
source control tools
Good for lone writers too (creates a
backup of your project)
Learning curve, especially with conflicts
Easy setup for the single-bound model
with Central
Can slow down Flare projects
![Page 30: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/30.jpg)
WHAT WE DO
• Main project (“Shared”)
– Dual-bound with Central
– First binding to Git, using branching (GitFlow)
– Second binding to Central
• Documentation Bible
– Single-bound to Central (no branching needed)
![Page 31: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/31.jpg)
WHAT WE DO
• “Develop” projects
![Page 32: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/32.jpg)
WHAT WE DO
• “Develop” projects
![Page 33: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/33.jpg)
WHAT WE DO
• “Develop” projects
– Single-bound to Central
– Child projects based on my “develop” branch
– These projects let us see files as the project is in development
• Task management
• Checklists
• Internal outputs
MadCap Doc Team Source Control PDF:
http://docs.madcapsoftware.com/doc-team/Source-Control.pdf
![Page 34: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/34.jpg)
Internal Architecture
![Page 35: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/35.jpg)
WHAT I’M COVERING IN THIS SESSION
• Naming Conventions
• Folders
• Snippets and Conditions
• Types of Topics
• Variables
• Stylesheets
• Tables of Contents
Things not covered in
this session are
discussed in detail in
the online Help.
![Page 36: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/36.jpg)
NAMING CONVENTIONS
• Word separation
– Hyphens: Recommended, better SEO
• Case
– Whatever you choose, try to use it consistently
• Length
– The shorter the better
• Keywords or letters
– Can add to beginning or end of names for better organization
• Meaningful names
– Applies to all types of files
![Page 37: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/37.jpg)
WHAT WE DO
• Hyphens for both folder and file names
• Case – Initial caps
• Try to keep minor words, such as articles, out of file names
• Keywords or letters for some file names
– “About-Page-Layouts.htm,” “About-Search.htm”
– “Elasticsearch-Summary.flsnp,” “Elasticsearch-Install-Steps.flsnp”
– “Save-btn.png,” “Search-btn.png,” “Font-btn.png”
• Still updating legacy files though
![Page 38: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/38.jpg)
FOLDERS
• Categories
– Intuitive names based on product or subject matter
• Conditions
– Conditions on folder can save time, applies to all files under it
• Order
– Can use characters or numbers to customize the order
![Page 39: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/39.jpg)
WHAT WE DO
• Categories
– Organized by product, then by feature
• Conditions
– Product conditions placed on folders
– Conditions on shared files
![Page 40: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/40.jpg)
SNIPPETS AND CONDITIONS
• Condition-focused versus snippet-focused topics
• Doesn’t mean you use only one or the other
• Has to do with which gets more “weight” in topics –
conditions or snippets
![Page 41: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/41.jpg)
SAMPLE TOPIC
![Page 42: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/42.jpg)
CONDITION-FOCUSED TOPICS
![Page 43: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/43.jpg)
SNIPPET-FOCUSED TOPICS
![Page 44: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/44.jpg)
Condition-focused Topics Snippet-focused Topics
Need only one topic Need to create multiple topics
Can be more confusing to edit,
especially with lots of conditions
applied
Easier to edit
May be easier or harder for SMEs to
review – what are these conditions?
May be easier or harder for SMEs to
review – what are these snippets?
![Page 45: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/45.jpg)
WHAT WE DO
• Snippet-focused topics
• Special “Shared” folders to store snippets that are used for
multiple products
• Let’s take a look…
![Page 48: Design of your documentation universe - MadCap Softwareassets.madcapsoftware.com/webinar/Presentation... · • Design of your documentation universe • Available options • Pros](https://reader030.vdocument.in/reader030/viewer/2022040413/5f0b5e597e708231d4302ceb/html5/thumbnails/48.jpg)
Questions