Best practices - recommended max. size of project?

Please post all questions on Help+Manual 8 here

Moderators: Alexander Halser, Tim Green

Post Reply
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Best practices - recommended max. size of project?

Unread post by Dave Gehman »

Our help file project is now 509 topics and 77,000 words. It is organized in three major sub-sections, self-guided training, concepts, and reference.

Is there a point at which best practices recommend "chunking up" a given single project into smaller sub-projects?

The very extensive H+M 8 help file -- doubtless dwarfing our efforts: is all of this material produced from a single project?
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: Best practices - recommended max. size of project?

Unread post by Martin Wynne »

Dave Gehman wrote: Tue Apr 07, 2020 5:55 pmThe very extensive H+M 8 help file -- doubtless dwarfing our efforts: is all of this material produced from a single project?
Hi Dave,

The manual from HM6 is available as one of the example projects. It's at:

C:\Users\user_name\Documents\My HelpAndManual Projects\Examples\HelpAndManual6\HELPMAN6.hmxp

cheers,

Martin.
User avatar
Olivier Beltrami
Posts: 393
Joined: Mon Jul 15, 2002 3:30 pm
Location: Nantes, France
Contact:

Re: Best practices - recommended max. size of project?

Unread post by Olivier Beltrami »

Hi,

Our main project contains 2373 topics, and we are generating regularly updated CHM, PDF and WebHelp versions with no issues. The only thing; make sure you save your project as HMXP rather than the compressed HMXZ format.

Very best regards,

Olivier
Olivier Beltrami
https://www.qppstudio.net
Worldwide Public Holidays and Calendar Data
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Best practices - recommended max. size of project?

Unread post by Tim Green »

Hi Dave,
The very extensive H+M 8 help file -- doubtless dwarfing our efforts: is all of this material produced from a single project?
Yes, that's all a single project and in Help+Manual terms it is quite compact. So long as you are using the uncompressed format the physical size of the project shouldn't really be your restriction. When and whether you use modules is more a question of how you want to use the material in other ways. For example, if there are large blocks of topics/chapters that you want to use in different contexts it makes sense to make a module out of them -- you can view that as a "project snippet".
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: Best practices - recommended max. size of project?

Unread post by Dave Gehman »

Thanks, Martin and Olivier - I had forgotten all about the example projects that come with H+M, and yes, our project has been the full type, HMXP, since the beginning.

Tim, you've given us quite a bit to think about, since one module, the self-guided training, should have several types of outputs before long. Or, rather, different contexts: online help, print manual, and (pie-in-the-sky) adjunct handout materials for in-person training -- any thoughts there in H+M Land in development or marketing around creating a PowerPoint output type?).
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Best practices - recommended max. size of project?

Unread post by Tim Green »

Dave Gehman wrote: Wed Apr 08, 2020 10:04 am Tim, you've given us quite a bit to think about, since one module, the self-guided training, should have several types of outputs before long.

Enabling that is one of the main reasons for the existence of all of Help+Manual's conditional output features. Modular projects are just one tool in that arsenal, for the big blocks of topics and chapters. You can also include and exclude individual topics and also any content within topics, using format-based and user-defined build options
Or, rather, different contexts: online help, print manual, and (pie-in-the-sky) adjunct handout materials for in-person training -- any thoughts there in H+M Land in development or marketing around creating a PowerPoint output type?).
An eWriter book without a TOC should cover that kind of thing if you're generating it from Help+Manual. However, HM is more focused on text-intensive content, so a HelpXplain presentation could actually be a better choice there.
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: Best practices - recommended max. size of project?

Unread post by Dave Gehman »

I'll d/l the trial version of HelpXplain.

I played with auto-summarizing software, using it to process H+M Word output about a year ago. I found a couple of packages that created some good presentation content that could provide the skeleton for live training presentations. But then I got inundated with real work and never honed a streamlined workflow -- that is, an expeditious process that didn't involve juggling several applications with too much hand-work.
User avatar
julio
Posts: 118
Joined: Wed May 28, 2008 12:06 am
Location: Porto Alegre, RS - Brasil
Contact:

Re: Best practices - recommended max. size of project?

Unread post by julio »

We have a product that demands different types of tutorials, and these tutorials contain topics or chapters that are common to all, so we created a project for each chapter and added custom builds to differentiate them. Then we created a single project with tables of contents for each tutorial and added the corresponding chapters to each one of those tocs. This may be challenging, specially when working with custom builds, but reduces duplicated work. Regarding the number of topics, we also have another project that contains ~3,300 topics and editing it is no big deal.
Dave Gehman wrote: Tue Apr 07, 2020 5:55 pm Our help file project is now 509 topics and 77,000 words. It is organized in three major sub-sections, self-guided training, concepts, and reference.

Is there a point at which best practices recommend "chunking up" a given single project into smaller sub-projects?

The very extensive H+M 8 help file -- doubtless dwarfing our efforts: is all of this material produced from a single project?
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: Best practices - recommended max. size of project?

Unread post by Dave Gehman »

Thanks, Julio. Some questions.
julio wrote: Thu Apr 09, 2020 12:13 pm We have a product that demands different types of tutorials, and these tutorials contain topics or chapters that are common to all, so we created a project for each chapter and added custom builds to differentiate them.
I'm not quite following. Why did you make separate H+M projects for each chapter -- and why (if each chapter is in a sense custom to a given application of your product) are projects set up with custom build? That is, aren't they already custom?
Then we created a single project with tables of contents for each tutorial and added the corresponding chapters to each one of those tocs.
Did you copy the contents of the smaller, separate projects into the over-arching project, the mega-project (the one with the comprehensive TOC)? Or did you link or snippet the smaller projects into the mega-project?
Regarding the number of topics, we also have another project that contains ~3,300 topics and editing it is no big deal.
Thanks again. I was thinking less about editing than of problems (in other software), such as managing large, complex documents in Word. At some point, Word would fail, leaving you with a corrupted document... anybody remember the disastrous "Master Document" stuff?
User avatar
julio
Posts: 118
Joined: Wed May 28, 2008 12:06 am
Location: Porto Alegre, RS - Brasil
Contact:

Re: Best practices - recommended max. size of project?

Unread post by julio »

1) All projects must have all custom builds, so we can control which part is compiled and where. Imagine that we have a chapter that is fully used by a tutorial but only used partially by another tutorial. When compiling the partially used one, we must know which part belongs to this tutorial and which part belongs to that tutorial, then use a IF-ELSE-ENDIF conditional.

2) No, all small projects are linked on the main project. If they were copied, any change would require a cascade of changes on all copies, that is why linked projects are the best way to handle this.
Dave Gehman wrote: Thu Apr 09, 2020 1:36 pm
I'm not quite following. Why did you make separate H+M projects for each chapter -- and why (if each chapter is in a sense custom to a given application of your product) are projects set up with custom build? That is, aren't they already custom?

Did you copy the contents of the smaller, separate projects into the over-arching project, the mega-project (the one with the comprehensive TOC)? Or did you link or snippet the smaller projects into the mega-project?
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: Best practices - recommended max. size of project?

Unread post by Dave Gehman »

julio wrote: Fri Apr 10, 2020 12:06 pm No, all small projects are linked on the main project.
Thanks again. A final question - how did you create the links? Did you insert the sub-projects as snippets? Or did you create a master project and add child projects (as in https://www.helpandmanual.com/help/hm_a ... t+projects)? Or did you use some other tactic?
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Best practices - recommended max. size of project?

Unread post by Tim Green »

Hi Dave,
Did you insert the sub-projects as snippets?
You can't insert projects as snippets, only single topics. If you want to insert a project you must use the project module method. Note that any project can be a master project for this. You can insert a project module in any TOC at any time.

Actually, you can even nest this: A project module can also contain a project module. We just don't emphasize this very strongly because it's very easy to get lost when you do this and the danger of circular references gets higher. A circular reference is the worst thing that can happen when working with modular projects: Project A contains Project B and Project B contains Project A. This creates an infinite recursion, like two mirrors facing each other. :)
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: Best practices - recommended max. size of project?

Unread post by Dave Gehman »

Thanks. I'm grateful to Julio for bringing this to our attention - I wouldn't have found the master / embedded projects strategy on my own... maybe someday I'll have to read the entire H+M help front to back. :)
User avatar
julio
Posts: 118
Joined: Wed May 28, 2008 12:06 am
Location: Porto Alegre, RS - Brasil
Contact:

Re: Best practices - recommended max. size of project?

Unread post by julio »

All projects are added to the main project by using one of the options on the contextual menu of a topic (Add Before, Add After, or Add Child). On the Insert New Topic or Chapter window, select the Include Help Project tab and then a project in the Project File option.

Dave Gehman wrote: Fri Apr 10, 2020 2:18 pm
julio wrote: Fri Apr 10, 2020 12:06 pm No, all small projects are linked on the main project.
Thanks again. A final question - how did you create the links? Did you insert the sub-projects as snippets? Or did you create a master project and add child projects (as in https://www.helpandmanual.com/help/hm_a ... t+projects)? Or did you use some other tactic?
Post Reply