Agile Documentation

Please post all questions and comments regarding Help & Manual 7 here.

Moderators: Alexander Halser, Tim Green

Post Reply
User avatar
Aitch
Posts: 544
Joined: Thu Jun 10, 2004 4:52 pm
Location: Manchester, UK

Agile Documentation

Unread post by Aitch »

Good morning all.

I've been quiet, but now I'm back, asking for some help with documentation.

We've teamed up with a new company who are writing online software and doing it Agile - so changes are being put through every 2 weeks.
Up to now, I've only dealt with 'final' software packages, where I get the software during QA phase and write the help file accordingly.

With the new software that's being written, they require the documentation to be up to date.

I've been working with the product owner and the UI designer, trying to come up with the best way to do this. I have several software packages I work on, but this is something completely new to me. I am the only one writing the help files, so the only one with H&M. I feel like I'm completely out of my depth.

Any help and feedback greatly appreciated.

Thanks
Heidi
Version 9.0.3 Build 6380

---------------------------------------------------------------------
Always check your spellar and gramming before you publish!
User avatar
Tim Green
Site Admin
Posts: 23154
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Agile Documentation

Unread post by Tim Green »

Hi Heidi,

Can they use WebHelp for their documentation? If they can, that is by far the best way to be able to update continuously. Whenever there is a change you just change it in Help+Manual and then push the change to the web server directly. It helps if you are using one of the recent Premium Pack skins, which assure that the users always see the latest version of each topic and the TOC and not the one from yesterday's cache.

If they are using local documentation together with the software, for example CHM or EWriter, then they need to have a copy of Help+Manual as well, and you both need to be working with version control (ideally Subversion). This is how we do it for Help+Manual's documentation. Then there is a master copy of the Help+Manual project on the Subversion server and both you and your clients have access to a linked local copy. When you make your changes you synchronize them with the server version and when the client re-publishes their software along with the documentation they first update the project by synchronizing it with the server version, which gets your changes, and then publish it out and include it with their software.

See this chapter in the help for details on version control:

https://www.helpandmanual.com/help/inde ... ed_vcs.htm
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.
User avatar
Aitch
Posts: 544
Joined: Thu Jun 10, 2004 4:52 pm
Location: Manchester, UK

Re: Agile Documentation

Unread post by Aitch »

Hello Tim

Thank you for your quick response. I don't think I have the latest PP - And trying to see where to find the version number of Premium Pack!
If not, I'll get it purchased and suggest this to the developers. We do use WebHelp with ours, but I don't publish to the server in our office. But the other office will probably have a different setup.

One more (related) question - can these be context sensitive too?
I have tried for many years to incorporate context sensitive help with our developers, but they're too busy to incorporate the numbers as well.. so we just have it as a plain HTML webhelp

Thanks Tim!

Heidi
Version 9.0.3 Build 6380

---------------------------------------------------------------------
Always check your spellar and gramming before you publish!
User avatar
Tim Green
Site Admin
Posts: 23154
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Agile Documentation

Unread post by Tim Green »

Aitch wrote:Thank you for your quick response. I don't think I have the latest PP - And trying to see where to find the version number of Premium Pack!

You can always see the installed Premium Pack version number in 1) The title of the Help+Manual Premium Pack chapter in the main Help+Manual help (or in the change log section therein, in older versions and 2) In the title bar of the Toolbox utility included with the Premium Pack.
I have tried for many years to incorporate context sensitive help with our developers, but they're too busy to incorporate the numbers as well.. so we just have it as a plain HTML webhelp
Plain HTML WebHelp is context sensitive; there's nothing you need to do to make it that way. Adding context numbers is only for users who are switching from CHM and want to continue to use exactly the same references. Context numbers generally are now deprecated, also in CHM, because they are so error-prone. Since they're just numbers they provide no information about what they refer to for humans, so it's all too easy to choose the wrong one and not notice. Context-help in CHM can also reference the topic ID/filename, and that is generally preferred.

For context help in WebHelp your programmers simply need to open a page on a website, using the same method they would to open any page on any website (generally "shellExecute" or something similar, if they ask). The URL syntax is explained in the help:

Standard HM Webhelp:
https://helpandmanual.com/help/index.ht ... ebhelp.htm

New Premium Pack V3 Webhelp:
http://www.it-authoring.com/info/pp3hel ... nking.html
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.
Post Reply