Cellprofiler: Documentation - use consistent order for help sections

[AnneCarpenter]

They certainly are not consistent at present (based on Primary vs Secondary vs Tertiary).

Perhaps someone knows the official rules. if not, as a straw man, I think this makes sense:

• Title, one liner, and intro help text describing the module
• Supports 2D/3D
• See also
• (module specific headings, unless they make sense elsewhere)
• What do I need as input?
• What do I get as output?
• Measurements made by this module
• Technical notes
• References
• Settings

Any suggestions are welcome!

Not sure about this section:

• What do the settings mean?
  This contains a description of the symbols used in the help (for some modules, and will be present in more soon, see #3171). I think it should go just before the settings section of the help but not knowing how the manual is built, I’m not sure how to accomplish it.

[mcquin]

@AnneCarpenter the manual currently does not support module settings help. It's unlikely it will in the near future.

I think that blurb could have a better home in the how to build a pipeline help. There's mention of checking the settings to see what they do. That could be a good place to point out what the symbols mean.

Additionally, I think 👍 and 👎 are pretty self-explanatory.

[AnneCarpenter]

Understood about the manual not showing settings. The ordering matters for when you show the full module help in CP's GUI, which includes the settings help though.

But I think I love the idea of removing this legend from modules altogether and putting it somewhere more introductory.

But actually, I think I vote to remove it altogether. It would be a rare soul who wants to read about symbols out of context from where they are used, and as @mcquin points out it's pretty self explanatory. That's my vote, just delete wherever found.

[mcquin]

Cool! I love deleting stuff :P

On Sep 15, 2017 11:01, "Anne Carpenter" [e-mail] wrote:

Understood about the manual not showing settings. The ordering matters for
when you show the full module help in CP's GUI, which includes the settings
help though.

But I think I love the idea of removing this legend from modules
altogether and putting it somewhere more introductory.

But actually, I think I vote to remove it altogether. It would be a rare
soul who wants to read about symbols out of context from where they are
used, and as @mcquin https://github.com/mcquin points out it's pretty
self explanatory. That's my vote, just delete wherever found.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/CellProfiler/CellProfiler/issues/3177#issuecomment-329808302,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AEgMW4YQhcgf8bWER9NQG1KLiaP8Vqcrks5sipFjgaJpZM4PYOSM
.

[AnneCarpenter]

I can do this one.

[mcquin]

@AnneCarpenter -- Your PRs removing "What do the settings mean?" have been merged. Is there anything else that needs to be done for this issue?

[AnneCarpenter]

The original issue does remain, actually.
I think if @bethac07 signs off on the straw man for the 'correct' ordering then @N3llz could check through modules to find any that disobey the rules and fix them.

[AnneCarpenter]

Needs @bethac07 's blessing. She is flying somewhere right now though.

[bethac07]

Consider yourself blessed ;)

On Wed, Sep 20, 2017, 2:31 PM Anne Carpenter [e-mail]
wrote:

Needs @bethac07 https://github.com/bethac07 's blessing. She is flying
somewhere right now though.

—
You are receiving this because you were mentioned.

Reply to this email directly, view it on GitHub
https://github.com/CellProfiler/CellProfiler/issues/3177#issuecomment-330852005,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AGaP6zbMZLX6bgdy-n564BSZhvnwQsz3ks5skROegaJpZM4PYOSM
.

[AnneCarpenter]

Added 2D/3D in the initial post.

[N3llz]

Should all of these sections have the same style heading? I've found some References sections that have the carrots under them (so they are big, bold headings) and others that have just two asterisks surrounding them. I'm wondering if this is a formatting inconsistency, or if the ones with asterisks are supposed to be within the Settings sections, and therefore do not need large headings.
So,

1. Are there some Refs sections that should be left as smaller sections within Settings?
2. Should all these sections listed above be of equal value (with regard to heading formatting, i.e. carrots underneath them)?

[N3llz]

I should add, some of these References seem to be embedded within the settings somehow, and must be called by a variable or something, because they don't show when I just Ctrl+F to search for "references". So if those refs SHOULDN'T be in the settings section, then this may be a separate issue. I'm thinking that some module settings do just intentionally have some of their own references?

[AnneCarpenter]

Great catch!

Generally, if references are truly a separate section they should have ^^^ like the rest of the headings.

However, it is true that some references sections are _within_ a setting, and those should only be bolded.

[N3llz]

Resolved by #3289
@0x00b1 OK to close this issue

[N3llz]

"Respects masks" will also be added as a new column to the 2D / 3D table (#2245)