开云体育

I am starting this topic following a more detailed look at the new Members Manual in connection with the earlier Enter Your Two Factor Authentication Code topic. I am raising it here rather than going direct to the beta docs Subgroup to see if my thoughts are shared by others or if I am just a lone voice.?

At first I looked at the pdf version, and found the section about 2FA very quickly; it is in the index and has a specific section number in the format x.y.z.

For no real reason I then did the same search using the "Single Page" version. 2FA is not individually indexed (although the same text is present once it is found) and there is no section numbering whatsoever. Although I will not pretend to have researched this exhaustively I came away with the conclusion that (a) the Index in the pdf version is better, and (b) the lack of section numbers in the single page version is a weakness.

Imagine two (or more) people trying to investigate something; one reports "I found <whatever> in section a.b.c on page (d)" and the other will say "I can't see any section numbers or page information".

Overall I much prefer the way the pdf version is presented; if there there are to be two different formats then IMHO their appearance should - insofar as is practicable - be the same.?

Do others on here share this view?

Chris

On Sat, Apr 18, 2020 at 10:45 AM, Chris Jones wrote:

Overall I much prefer the way the pdf version is presented; if there there are to be two different formats then IMHO their appearance should - insofar as is practicable - be the same.

I agree that they should use the same 'format' if at all possible, though I can see where "page (d)" wouldn't be of much use in the online version.? I have a repair manual for my car that has different formats for printed and electronic versions.? Makes it difficult to exchange information until I can get my head wrapped around how to switch.

Based on Nina's comments about the changes from yesterday (several messages on the docs group), I believe this is still a work in progress and fine tuning like this will get done.

Duane
--
GMF's Unofficial Help Wiki: /g/GroupManagersForum/wiki
The official Groups.io user documentation is in the Groups.io Help Center.

On Sat, Apr 18, 2020 at 05:07 PM, Duane wrote:

Based on Nina's comments about the changes from yesterday (several messages on the docs group), I believe this is still a work in progress and fine tuning like this will get done.

One has to hope, but at the same time might it be worth pointing the differences rather than the existing formats remaining by default?

For now let's see if others have anything to add.

Chris

On Sat, Apr 18, 2020 at 04:45 PM, Chris Jones wrote:

Overall I much prefer the way the pdf version is presented;

Agreed, and in the comments I have posted on docs about the manuals I have always tried to include a reference based upon the PDF document. I think it makes items much easier to find.

Andy

Chris,

Although I will not pretend to have researched this exhaustively I
came away with the conclusion that (a) the Index in the pdf version is
better, and (b) the lack of section numbers in the single page version
is a weakness.

It is, but I've been assuming that the single-page version is a stop-gap that allows the use of browser search capability. It will be much less interesting once the primary (multi-page) version has a dedicated search feature. Maybe it will even be taken down at that point (I actually hope not).

... if there there are to be two different formats then IMHO their
appearance should - insofar as is practicable - be the same.

That's an ideal, but I think the three formats that are there right now serve different purposes, and their formatting distinctions go with the use case.

An argument against section numbers in the online version has been made, noting that those numbers "rot" as the document content evolves: Add a new section and that changes the numbering of ensuing sections at the same level. That kind of behavior is a poor experience for an online document that is supposed to be revised as needed. The text that you read in section 1.3 just now might be in section 1.4 seconds after you cite it.

On the other hand, in print (PDF) documents that kind of "rot" is integral to the semi-permanent format. This kind of document is like a physical book: for an accurate citation you must include the edition of the document as well as the section number.

For online documents some form of Permalink mechanism would be my preference - a link icon with each section header, and the underlying URL unchanging. The old Help pages have that (they appear when you hover to the left of the header), but only for the top-level headers:
/static/help

I'd make them always visible, and on all header levels. Possibly over to the right edge, more like message number permalinks.

I'd also make their URLs as short as practical, even to the point of using a serial number for each section rather than a mnemonic. That is, i'd rather see something like:
/helpcenter/membersmanual/539
than a monstrosity like:
/helpcenter/membersmanual/1/understanding-groups-io-accounts/setting-account-preferences-and-viewing-account-information#Setting-up-two-factor-authentication
but that's a battle I'm likely to lose.

Shal


--
Help: /static/help
More Help: /g/GroupManagersForum/wiki
Even More Help: Search button at the top of Messages list

On Sun, Apr 19, 2020 at 07:26 AM, Shal Farley wrote:

An argument against section numbers in the online version has been made, noting that those numbers "rot" as the document content evolves: Add a new section and that changes the numbering of ensuing sections at the same level. That kind of behavior is a poor experience for an online document that is supposed to be revised as needed. The text that you read in section 1.3 just now might be in section 1.4 seconds after you cite it.

Shal; your post covered several points within the overall subject, so it was not easy to decide which bit to quote!

I can see the point you are making above, but have reservations about it. I can see that "rot" could be a problem with draft and early issues of a document, but over time things should stabilise, perhaps following the early part of a bathtub curve, hopefully never reaching the end where the curve shoots rapidly upwards again! Where numbering exists in the form that is currently used (in the pdf version, obvs) it is easy to add bits without screwing up the entire document; an existing example is section 4.4.X. where X is currently in the range 1 to 9. That could easily become a range of 1 to 99 without it upsetting anything else in the process. Without numbering trying to refer anyone to any given section may be unnecessarily problematic, so for now at least I think numbering is (much) better than no numbering.

Having said that I have found other concerns; while the sections about Files (15) and Photos (17) have this warning very close to the beginning of each section:

Note: Group owners determine whether the Files feature is available in their groups and, if it is, who can
view and upload files: all members or only owners and moderators. (or Photos as the case may be)

A little later there are sections for Uploading Files / Uploading Photos with tables showing the sequence of operations to be carried out. Below each of those sections there is another caveat:

Note: If the Upload File button or Upload Directory button is not available, either the group has reached
its storage limit or members are not allowed to upload files to the group.

Now IMHO that caveat ought to be the first entry in the table, not appended underneath it where the member will not see it until after he or she has tried to follow the instructions and failed.

Another concern is that while things like setting up, Files, Photos, and Hashtags (and so on) each have their own defined sections there is no defined section about Attachments, although various salient points about them are included overall. What is not included (as far as I can see after several searches) is the highly salient point that a Group Owner may have decided not to enable attachments, so a member who finds that their attachments don't work will find no help from the Members Manual whatsoever.

At the moment I am reluctantly coming to the conclusion that in the event of any "difficulty" arising I could not with a clear conscience point any enquiring member towards the Manual for fear that they won't be able to find an answer, and even more relucantly coming to the conclusion that my trying to iron out any initial anomalies may be a fruitless exercise.

Chris

Chris,

Shal; your post covered several points within the overall subject, so
it was not easy to decide which bit to quote!

I'd say quote in segments, but that's not as easy to do on site as it is in Thunderbird.

... it is easy to add bits without screwing up the entire document;

Granted. But how much gets renumbered depends on how high up in level structure, and how early within each level the insertion or deletion occurs.

Without numbering trying to refer anyone to any given section may be
unnecessarily problematic, so for now at least I think numbering is
(much) better than /no/ numbering.

I think using a section title as the text of a link, and the permalink as its URL would work out fine. Even without permalinks at all levels (as I'd prefer), the browser URLs you can obtain from the address bar in the current multi-page document at least gets the user to the right page, and citing the subsection title from there is an easy scroll + eyeball search.

Having said that I have found other concerns; ...

These of course can be brought to the docs group for improvement / correction.


Or, perhaps update or create the relevant pages in GMF's wiki first, if you'd like to have both a more immediate "fixed" text that you can cite, as well as offering it to others for review.

Shal


--
Help: /static/help
More Help: /g/GroupManagersForum/wiki
Even More Help: Search button at the top of Messages list