Date   

Re: New help center

West Coast Compañeros Staff
 

Even though some of the items are just placeholders promising content yet to come, the new Help Center represents a quantum leap forward. Up till now there have been various helpful resources available for both members and owners/moderators, but they have been scattered around, making it difficult to perform a systematic and comprehensive search. The Help Center now provides a central hub to facilitate such a focused search. Kudos for launching this, especially in such challenging times.

I suggest that you also include a link to the Group_Help home page next to the link to the Group Managers Forum in the intro. Even though that group doesn't yet enjoy as much popularity as GMF, it is still a valuable resource for issues that affect most members versus the special needs of owners & moderators.

Robert R.

On 3/24/20 1:46 PM, Mark Fletcher wrote:

I've put up an alpha version of the new help center, here: https://groups.io/helpcenter

Please let me know what you think.

Thanks, Mark


Re: New help center

Nina E
 


At some point there will be a search feature.
A future search feature seems redundant.
When viewing HTML and also PDF (online) Ctrl/F give a fairly easy to use and comprehensive search facility.
Speaking with my user hat on (rather than my tech writer hat :-) ), a search feature that's available throughout the help center would (I hope) provide search results in context—similar to wiki searches in groups, maybe—which would make for a good user experience.

- Nina


Re: New help center

 

Hello,

Thanks for the suggestions for improvements of the PDF versions of the manuals. I've made the following changes to the PDF version of the Owners Manual:

- There are now page breaks before each new section.
- We do a page break if we can only fit a couple lines of a subsection at the bottom of the page (mostly, I've seen at least one instance where this isn't fixed yet).
- Table headers are now repeated if the table spans multiple pages (with the exception of any table that has a nested table, because there is a bug in the utility I use that causes overlapping text in that instance).
- There's a new header on every page with the section title.
- I've tweaked the header and footer spacing of the page.

In non-PDF manual news, I fixed a bug when viewing the manual section by section that caused some sections to not be displayed.

I have also updated the Owners manual to the latest version.

Thanks,
Mark

On Sun, Mar 29, 2020 at 9:53 AM Mark Murphy <mark@...> wrote:
This is such a useful document and I know a great deal of work has gone into it. I hesitate to ask for more, however... I have some suggestions.
 
1. Section 26.3 Bounce, bouncing
 
Consider also mentioning "system bounces" if a message cannot be delivered to a group due to a group policy or system limit. For example, sections 4.6.4 (Hashtag permissions), 4.6.13 (Storage Limit Reached), 4.8.6 (Message that contain attachments), etc.
 
2. Tables
 
Repeat table headings when a table is split over pages.
 
3. Formatting topmost outline level
 
Use outline notation with ending period at the top outline level. For example, use "2. Conventions used in this documentation" rather than "2 Conventions used in this documentation". This helps to visualize and emphasize the outline levels of the document.
 
Consider using page breaks to separate changes in top outline level.
 
4. Page headers
 
Consider adding a header to all pages which contains the current top level (single digit) heading of that page. For example, the header on Section 4 pages 13-29 would be "4. Customizing Group Settings." This helps for wayfinding and context for the reader to know where they are within the document.
 
5. Apparent links within the document to Glossary items do not work. (formatting tweaks?)
 
6. Minor cleanup
 
Replace subscriber with member in sections 4.8.2, 4.8.3, 4.9.1, etc.
 
Thank you for producing this wonderful Owners Manual!


Re: New help center

Bob Bellizzi
 

On Tue, Mar 24, 2020 at 01:46 PM, Mark Fletcher wrote:
At some point there will be a search feature.
A future search feature seems redundant.
When viewing HTML and also PDF (online) Ctrl/F give a fairly easy to use and comprehensive search facility.
 
--
Bob Bellizzi


Re: New help center

Mark Murphy
 

This is such a useful document and I know a great deal of work has gone into it. I hesitate to ask for more, however... I have some suggestions.
 
1. Section 26.3 Bounce, bouncing
 
Consider also mentioning "system bounces" if a message cannot be delivered to a group due to a group policy or system limit. For example, sections 4.6.4 (Hashtag permissions), 4.6.13 (Storage Limit Reached), 4.8.6 (Message that contain attachments), etc.
 
2. Tables
 
Repeat table headings when a table is split over pages.
 
3. Formatting topmost outline level
 
Use outline notation with ending period at the top outline level. For example, use "2. Conventions used in this documentation" rather than "2 Conventions used in this documentation". This helps to visualize and emphasize the outline levels of the document.
 
Consider using page breaks to separate changes in top outline level.
 
4. Page headers
 
Consider adding a header to all pages which contains the current top level (single digit) heading of that page. For example, the header on Section 4 pages 13-29 would be "4. Customizing Group Settings." This helps for wayfinding and context for the reader to know where they are within the document.
 
5. Apparent links within the document to Glossary items do not work. (formatting tweaks?)
 
6. Minor cleanup
 
Replace subscriber with member in sections 4.8.2, 4.8.3, 4.9.1, etc.
 
Thank you for producing this wonderful Owners Manual!


New help center

 

Hi All,

I've put up an alpha version of the new help center, here: https://groups.io/helpcenter

It contains a link to the most recent version of the Owners Manual (the other manuals are not yet ready for review).

  • The owner's manual is mostly complete.
  • Note that the PDF is missing the images from the manual and final formatting tweaks.
  • Also, at the end of the manual are some notes from Nina to me about remaining items; those will removed in the final version.
  • At some point there will be a search feature.
  • The lorem ipsum placeholder text will be replaced.

Please let me know what you think.

Thanks, Mark


Re: Additional Suggestions

Duane
 

I don't understand your suggestions.  I see no need for the blurb.  The questions you asked are answered elsewhere and the document is correct as is.  BTW, the answers are No and Yes.

Duane


Additional Suggestions

Bill Hazel
 

Page 5 - Group Title
  • Add blurb that the Group Title may include spaces, plus signs, slashes, periods, and underscores (if true)
Page 10 - Messages
  • Messages from members can only be tagged with existing hashtags, new hashtags will be removed
    QUESTION: Do the Moderators see the hashtag? They might think they are a good idea
Page 10 - Messages
  • Disable Editing Messages
    QUESTION: If not disabled, can the message be edited after it is replied to?


Re: Owner/Mod manual corrections and suggestions

Duane
 

On Sat, Mar 14, 2020 at 11:07 AM, Mark Fletcher wrote:
I used the term panel because that's what those things are called in the web framework that I use to build the site (called Bootstrap). I personally have no opinion on what they should be called in the documentation.
Since you're comfortable with that term, and have used it as a reference here, I think it should be used in the documentation as well.  As I mentioned on the GMF group, "section" didn't seem quite specific enough somehow, but "panel" seems to be perfect - a separate area that's clearly delineated.  I intend to start using it when needed.

Thanks,
Duane


Re: Owner/Mod manual corrections and suggestions

Kristen James Eberlein
 

If Nina selects a style guide, it will outline the terminology to use for UI components.

Best, Kris


On Mar 14, 2020, at 12:07 PM, Mark Fletcher <markf@corp.groups.io> wrote:


On Sat, Mar 14, 2020 at 7:04 AM Duane <txpigeon@...> wrote:
Based on an almost minor comment that Mark made, I think the entire document should be edited so that references to a "section" of a page, such as "The page contains sections for these categories of settings:" on page 14 under General settings, should be changed to "The page contains panels for these categories of settings:"  I was going to make a list of them, but there are a lot of them throughout the manual.

I used the term panel because that's what those things are called in the web framework that I use to build the site (called Bootstrap). I personally have no opinion on what they should be called in the documentation.

Thanks,
Mark 


Re: Owner/Mod manual corrections and suggestions

 

On Sat, Mar 14, 2020 at 7:04 AM Duane <txpigeon@...> wrote:
Based on an almost minor comment that Mark made, I think the entire document should be edited so that references to a "section" of a page, such as "The page contains sections for these categories of settings:" on page 14 under General settings, should be changed to "The page contains panels for these categories of settings:"  I was going to make a list of them, but there are a lot of them throughout the manual.

I used the term panel because that's what those things are called in the web framework that I use to build the site (called Bootstrap). I personally have no opinion on what they should be called in the documentation.

Thanks,
Mark 


Re: Owner/Mod manual corrections and suggestions

Duane
 

Based on an almost minor comment that Mark made, I think the entire document should be edited so that references to a "section" of a page, such as "The page contains sections for these categories of settings:" on page 14 under General settings, should be changed to "The page contains panels for these categories of settings:"  I was going to make a list of them, but there are a lot of them throughout the manual.

Possibly in the Terminology/Glossary page, add this definition.

"CHANGE: Separate the settings in the Default Sub Settings page into two panels for greater clarity." in https://beta.groups.io/g/main/message/24495

Good luck keeping up with Mark!

Duane


Re: Overall style points

Kristen James Eberlein
 

I did not see style inconsistencies. I suggested a style guide because it can be useful in the following ways:

  • Authors can follow the rules that the style guide lays out, rather than taking time to make decisions such as "Should I use sentence-style or headline-style for headings?" -- or remember previous decisions.
  • Prevents stylistic inconsistencies
Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
OASIS Distinguished Contributor
Principal consultant, Eberlein Consulting LLC
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 3/11/2020 8:22 PM, Mark Fletcher wrote:
On Wed, Mar 11, 2020 at 4:23 PM Marv Waschke <marv@...> wrote:
I'll second "adopt a style guide and stick to it." I also prefer the IBM guide, but following the guide consistently is much more important than the guide chosen.

 
Maybe this is my ignorance talking, but what style inconsistencies are there in the doc right now? 

Thanks,
Mark


Re: Overall style points

Nina E
 

Thank you, Shal! I appreciate your taking time to review the document and welcome your comments whenever you have a chance.

Best,
Nina

-----Original Message-----
From: docs@beta.groups.io <docs@beta.groups.io> On Behalf Of Shal Farley
Sent: Friday, March 13, 2020 1:39 AM
To: docs@beta.groups.io
Subject: Re: [docs] Overall style points

Nina,

> I'm fully aware of best practices for page breaks, ...

My apologies. I didn't mean to imply that you didn't.

> and yes, Google Docs does have "keep lines together" and "keep with > next" options, which I am applying as needed.

Ok, that's good to know. I was concerned that it did not have that capability. I guess I over-interpreted what you meant by having to "redo" too many of them.

> But getting the content written and ensuring its accuracy are higher > priorities for me at the moment than page breaks for PDF printing.

I wholeheartedly agree.

I just wish I had more time during the week so that I might give you more substantive comments, but it is crunch time for me at work.

Shal


Re: Overall style points

 

Nina,

I'm fully aware of best practices for page breaks, ...
My apologies. I didn't mean to imply that you didn't.

and yes, Google Docs does have "keep lines together" and "keep with
next" options, which I am applying as needed.
Ok, that's good to know. I was concerned that it did not have that capability. I guess I over-interpreted what you meant by having to "redo" too many of them.

But getting the content written and ensuring its accuracy are higher
priorities for me at the moment than page breaks for PDF printing.
I wholeheartedly agree.

I just wish I had more time during the week so that I might give you more substantive comments, but it is crunch time for me at work.

Shal


Re: Overall style points

Nina E
 

I don't know what formatting Google Docs is capable of but you really want marking for conditional page breaks (such as Word's "Keep with next" style option) so that the page breaks are only present where needed. You may need to add a few at each "final" draft, but you never need to re-do the ones you've done.<<
I'm fully aware of best practices for page breaks, and yes, Google Docs does have "keep lines together" and "keep with next" options, which I am applying as needed. But getting the content written and ensuring its accuracy are higher priorities for me at the moment than page breaks for PDF printing.

- Nina


Re: Overall style points

 

Mark,

Maybe this is my ignorance talking, but what style inconsistencies are
there in the doc right now?
I haven't really paid attention to that, but Nina's earlier reply to me made me wince:

5) For the PDF pay attention to page breaks.
For sure. I'm waiting until the final draft, so I don't have to redo
too many. :-)
It implies to me manual insertion of page breaks, and that never ends well.

I don't know what formatting Google Docs is capable of but you really want marking for conditional page breaks (such as Word's "Keep with next" style option) so that the page breaks are only present where needed. You may need to add a few at each "final" draft, but you never need to re-do the ones you've done.

And yes, I throw scare quotes on the word "final", as I expect the site and its manual to continue evolving.

Shal


Re: Overall style points

 

Marv wrote:

I am not a big fan of elaborate numbering systems in living documents.
I'll agree for the online (HTML) document; some form of permalinks to the headings would be ideal for citation.

Numbers look nice, but I've been misled by them too often to like
them.
For the PDF, which one might print, a human-readable heading identifier would be my preference. And my favorite of those is simple header level numbering (e.g. 1, 1.1, 1.2, 2, 2.1, 2.1.1, 2.1.2, 2.2, 3, ...). If the headings are styled in a way that makes those stand out then it is easy to skim through the pages and keep track of where you are.

I recognize that the difficulty in those two use cases would be in finding a way to author both styles from a single source document, given the authoring tool at hand.

Shal


Re: Overall style points

 

On Wed, Mar 11, 2020 at 4:23 PM Marv Waschke <marv@...> wrote:
I'll second "adopt a style guide and stick to it." I also prefer the IBM guide, but following the guide consistently is much more important than the guide chosen.

 
Maybe this is my ignorance talking, but what style inconsistencies are there in the doc right now? 

Thanks,
Mark


Re: Overall style points

Marv Waschke
 

I'll second "adopt a style guide and stick to it." I also prefer the IBM guide, but following the guide consistently is much more important than the guide chosen. As much as you can, embody the style guide in a word processing template. I've worked on many industry standards groups (including a few OASIS groups) and a well-wrought template saves a tremendous amount of error-prone and tedious work when enforcing consistency and adjusting appearance to suit different media. I haven't used Google Docs much, so I don't know its capabilities, but Msft Word styles are so useful, they are the reason I use Word. I even remove the font, size, bold, etc. section from my Word ribbon so I am never tempted to change appearance without changing the style.

I am not a big fan of elaborate numbering systems in living documents. As sections are added, deleted, and moved around, references to the numbers tend to get stale, i.e. wrong. I prefer hyperlink xrefs that are more durable as the doc changes. Numbers look nice, but I've been misled by them too often to like them.

The doc itself looks very good to me. Good work! Keep it up.
Marv

341 - 360 of 383