Date   

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


Owner/Mod manual corrections and suggestions

Duane
 

All page numbers shown are using the total pages, not the one at the bottom.
----------
pg 12
When using the menu>submenu>page section, it seems to me that an additional notation should be used.  As an example, Admin > Settings, Spam Control to refer to that section of the Settings page.  To go a step further, it could be Admin > Settings, Spam Control > Announcement-Only Group for an area within that section.
----------
pg 15
Change "Tip: If you want to promote your group, use appropriate keywords in the group title so..." to "... keywords in the group title or description so..." in the Group Title section as well as in the Group Description section.
----------
pg 22
The indicated link for "Viewing and managing your group’s storage space" is not active.
----------
pg 23
The indicated link for "Email Delivery" in the second bullet point is not active.
----------
pg 27
Under Wiki Settings, Permissions, there should be a Note:
Note: Wiki pages can be restricted to moderator modification when created.
----------
pg 28
Email Delivery, Full Featured Digest
Due to the recent change, "Any messages that remain at the end of the day are sent as the final (or only) digest of the day." should be changed to "Any messages that remain at 6 AM local time are sent as the final (or only) digest of the day, if a digest has not been sent within the last 6 hours.
----------
pg 31
Overview, 3rd sentence, typo - "...having an member notice..." should be "...having a member notice..."
----------
pg 32
Include a link to an example Direct Add Notice?
----------
pg 33
For clarity change "When the notice is created, a Guidelines entry automatically appears on the group’s home page." to "...appears on the left menu of the group’s home page."
----------
pg 33
Email Subject bullet.  Change from "Enter a subject line that will appear in the message in the group archive, if the notice is emailed monthly to the group." to "...will appear in the message when emailed, either to the group or an individual."
----------
pg 34
Locked Group notice.  Add:
Note: Only paid groups may be locked.
----------
pg 35
Link to an example Welcome Notice, possibly the default that's automatically created?
----------
pg 36
Sending invitations to join the group
item 4 - format of email address may be:
<name> email@... or email@...
----------
pg 37
Under "To cancel and remove invitations", item 2, add note:
Note:  If you do not cancel/remove an invitation, it can be used at any future date.
----------
pg 38
The badge is missing for Moderate First
----------
pg 38
several places, the indicated link for "posting privilege" is not active.
----------
Pg 38
NMM badge, "...posts (1, 2, 3, or 4) required before..." should be changed to "...posts (1, 2, 3, or 4) remaining before..."
----------
pg 40
at the bottom, "The note will be saved in the member’s record, which will be retained..." needs to indicate that Past Members are only available to paid groups.
----------
pg 46
Handling an individual pending message, Edit, Note, "...(however, it does not prevent other moderators from taking action)." should be changed to "...moderators from taking action online)."
----------
pg 47
item 4, "Approve & Unmoderate Senders: Approve the selected pending messages and take their senders off moderation." should be "...messages and change their senders to Use Group Moderation Setting."
----------
pg 51
item 5, "Save Without Sending: Use this button if you want to just save the edited message in the archive without emailing it to group members." change to "...without emailing it to all group members and a copy will be sent to the original poster."
----------
pg 51
near bottom, indicated link for "pending group members" not active
----------
pg 52
Receiving and viewing messages sent to the owner email address, bullet 2, "...to list all messages that have been sent to the owner email address." should be "...messages that you have sent..."
----------
pg 53
Under "Managing hashtags", Overview, for completeness, "...hash (or pound or number sign)..." should be "...hash (or pound, number sign, or octothorpe)..."
----------
pg 55
Section "Usage settings on individual hashtags" typo "...Use by Use by Mods Only..." should be "...Use by Mods Only..."
----------
pg 63
Under "Viewing your group’s storage limit and current space usage", can also see usage by going to https://groups.io/g/[groupname]/usage
----------
pg 64
Under "Adding an email integration", item 3, "Hashtags: Enter any hashtags (up to five) that you..." should be changed to "...(up to four, plus the automatic #email)..."
----------
pg 65
Under "Adding a feed integration", item 3, "Hashtags: Enter any hashtags (up to five) that you..." should be changed to "...(up to four, plus the automatic #feed)..."
----------
pg 70
"Groups.io gathers the selected data into a compressed zip archive and, generally within 10 minutes, sends you an email message with a link to the data file." should have added "...link to the data file that is valid for 24 hours."
**********

Hope I'm not being too nit-picky!

Duane


Re: Overall style points

Kristen James Eberlein
 

Nina, many thanks for your work on the documentation. I found it very useful.

Just a few comments:

  • Consider adopting a style guide and sticking to it. There are several widely used in the industry, including Microsoft Manual of Style and IBM Style Guide. The latter is my personal favorite and what I most often recommend to clients.
  • Sentence-style headings are best. All usability studies (dating back to the 1950s) show that it is more readable than the alternatives. If the headings are not standing out from the text, that's a reason to adjust how the headings are styled, for example, font size or color or a bottom border.
  • PDF bookmarks would be wonderful and make the document much more usable, but I don't know if Google docs can accommodate that :(

I moved a group (DITA Users) from Yahoo! to Groups.io last fall, and I am extremely happy with the platform. And BTW, lots of technical communicators in our group!

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/10/2020 7:09 PM, Nina E wrote:

Hi, all. I'm the writer working on the Groups.io documentation. Thank you for the comments on the owner/moderator reference doc so far!

To address some of the points that Shal raised:

1) How about Title Case for section titles? I think that would help them stand out in the document body.

I used sentence case from force of habit because that was the standard in my last tech writing/editing job. :-) That said, because many headings contain proper nouns (names of web pages, menu items, fields, and so on), I think sentence case helps those proper nouns stand out in the headings. Also, numbering will help the headings stand out (see the next item).

2) How about section numbers?

I agree that heading numbers will help in the printed/PDF version. (I'm not convinced that heading numbers are terribly useful in online presentation, but we'll see how it goes.) I didn't include them initially because I'm writing the documentation in Google Docs (that's the approach Mark and I agreed on when I first contacted him), and Google Docs doesn't have a heading numbering feature built in. However, I recently found an add-on that does the trick, so I'll try that in the next draft.

4) PDF Bookmarks, please!

As I mentioned above, I'm currently using Google Docs, but I'm not very familiar with its export-to-PDF capabilities. Maybe there's an add-on that will add bookmarks to PDF files; I'll look around. (If anyone happens to know of such a Google Docs add-on, please let me know.)

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. :-)

6) For the PDF consider using a new page for selected headings. All Heading 1 likely, and maybe all of Heading 2 as well.

Good suggestion - I'll give it a try.

Thank you again!

Regards,
Nina

P.S. For the record, I own/moderate a restricted Premium group for a chorus of which I'm a member, and I serve as secretary on its board. We transferred our group from Yahoo Groups to Groups.io two years ago this February, and we couldn't be happier that we did so!


Re: Feedback about documentation: Kudos!

Nina E
 

Thank you so much, Kris!

- Nina (the writer)


Re: Glossary?

Nina E
 

Hi, Bill. As I mentioned in another post, I'm using Google Docs to write the Groups.io documentation. I put the glossary in a document of its own to avoid duplicating it in both the owners/moderators reference doc and the members/reference doc, but then I discovered that linking between Google Docs is...less than ideal. :-(  Rest assured that Google Docs will NOT be the final repository for the official Groups.io documentation. Mark and I (but mostly Mark :-) ) will work on how best to publish the documentation in PDF and online/HTML form such that the links will work.

I'm using the current Groups.io help as well as a lot of info from GMF (especially the wiki) and Beta as resources for the content in the documentation, so you will see some duplication for a while. By the way, huge thanks to all of you who have contributed to those resources over the years!

- Nina


Re: The description of Time/Date controls in Default Sub Settings is wrong

Nina E
 

Thanks, Shal! Mark and I are working on clarifying that settings page and correcting the information in the documentation.

- Nina


Re: Overall style points

Nina E
 

Hi, all. I'm the writer working on the Groups.io documentation. Thank you for the comments on the owner/moderator reference doc so far!

To address some of the points that Shal raised:

1) How about Title Case for section titles? I think that would help them stand out in the document body.

I used sentence case from force of habit because that was the standard in my last tech writing/editing job. :-) That said, because many headings contain proper nouns (names of web pages, menu items, fields, and so on), I think sentence case helps those proper nouns stand out in the headings. Also, numbering will help the headings stand out (see the next item).

2) How about section numbers?

I agree that heading numbers will help in the printed/PDF version. (I'm not convinced that heading numbers are terribly useful in online presentation, but we'll see how it goes.) I didn't include them initially because I'm writing the documentation in Google Docs (that's the approach Mark and I agreed on when I first contacted him), and Google Docs doesn't have a heading numbering feature built in. However, I recently found an add-on that does the trick, so I'll try that in the next draft.

4) PDF Bookmarks, please!

As I mentioned above, I'm currently using Google Docs, but I'm not very familiar with its export-to-PDF capabilities. Maybe there's an add-on that will add bookmarks to PDF files; I'll look around. (If anyone happens to know of such a Google Docs add-on, please let me know.)

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. :-)

6) For the PDF consider using a new page for selected headings. All Heading 1 likely, and maybe all of Heading 2 as well.

Good suggestion - I'll give it a try.

Thank you again!

Regards,
Nina

P.S. For the record, I own/moderate a restricted Premium group for a chorus of which I'm a member, and I serve as secretary on its board. We transferred our group from Yahoo Groups to Groups.io two years ago this February, and we couldn't be happier that we did so!

361 - 380 of 397