Question on Style and Conventions

This forum is for the discussion of the business and craft of writing help. For example writing style, choices of HTML Help or WinHelp or browser-based and so on...

Moderators: Alexander Halser, Tim Green

Question on Style and Conventions

Unread postby Olivier Beltrami » Wed Jan 02, 2019 3:57 pm

Hi,

I am going back through my software's documentation, begun in 2001 with the H&M beta, trying to clean-up old Windows 2000 screenshots and outdated and/or overly verbose topics, as well as trying to be more consistent.

My main conundrum has to do with links.

    1. Suppose a topic mentions "macros" 4 times. Currently, I insert a link to the corresponding topic with the first occurrence of "macros". But, what should be done about the 3 other occurrences ? Leave them plain, make them italics, repeat the link 4 times ?

    2. I also place some links in a "See also" section at the bottom of many topics. Is it OK to repeat in the "see also" section, some of the earlier links ?

    3. Finally, the titles in the TOC have proper capitalization (eg. "The Main Window"), and for the moment, any links to such a TOC entry would also have its link capitalized. But I find that when there are many links in a topic, there is just too much caps everywhere. Should I make the text of the link un-capitalized (eg. "the main window") ?

Any thoughts are welcome.

Very best regards,

Olivier
Olivier Beltrami
www.qppstudio.net
Worldwide Bank and Public Holidays and Calendar Freeware
User avatar
Olivier Beltrami
 
Posts: 232
Joined: Mon Jul 15, 2002 3:30 pm
Location: Nantes, France

Re: Question on Style and Conventions

Unread postby Tim Green » Thu Jan 03, 2019 11:19 am

Hi Olivier,

1. Suppose a topic mentions "macros" 4 times. Currently, I insert a link to the corresponding topic with the first occurrence of "macros". But, what should be done about the 3 other occurrences ? Leave them plain, make them italics, repeat the link 4 times ?

I think it is fine to just link to it once. The user doesn't need that much hand-holding, and providing it will get in the way of the majority of users who don't need it. It's fine that the user knows that the topic covers macros. That's enough. Then they need to read the topic, and that is really up to them.

2. I also place some links in a "See also" section at the bottom of many topics. Is it OK to repeat in the "see also" section, some of the earlier links ?

This is really something you need to decide on a case-by-case basis. The question is always:

1) Is this something that someone reading this topic will want to know and read after this topic?
2) Are there so many links here that I'm making the important ones less accessible?

It's a balancing act: Put in too many links and the important ones won't get seen. Don't put in enough and the users will get less important information. You'll never get it 100% right. 8)

3. Finally, the titles in the TOC have proper capitalization (eg. "The Main Window"), and for the moment, any links to such a TOC entry would also have its link capitalized. But I find that when there are many links in a topic, there is just too much caps everywhere. Should I make the text of the link un-capitalized (eg. "the main window") ?

There aren't really any hard and fast rules about this and personally I think it's fine. The simple fact that the links are links sets them apart from the rest of the text enough already. If the additional capitalization looks jarring it's better to change it rather than try to match the TOC links exactly.
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
Tim Green
Site Admin
 
Posts: 20585
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany

Re: Question on Style and Conventions

Unread postby Olivier Beltrami » Tue Jan 08, 2019 3:36 pm

Hi Tim,

Thank you very much for your detailed and, as always, informative response.
I have been digesting it and testing things out.
But consistency is so hard to achieve. :?

Very best regards,

Olivier
Olivier Beltrami
www.qppstudio.net
Worldwide Bank and Public Holidays and Calendar Freeware
User avatar
Olivier Beltrami
 
Posts: 232
Joined: Mon Jul 15, 2002 3:30 pm
Location: Nantes, France


Return to Help Authoring

Who is online

Users browsing this forum: No registered users and 1 guest

cron