2
$\begingroup$

Once upon a time, there were no nodes, the world was still simple then.

There were main menus, context menus, input fields, keyboard shortcuts, etc. and the highest of feelings were a few lines of Python code. That's probably when the style guide on BSE evolved.

But then came nodes.
And more and more came.

And no one thought to consider a new style element for it consistently!

As surely some of you might have noticed, in all my posts I write the names of the Geometry Nodes available in Blender in backticks.

Why do I do this?

I have noticed with some test persons (primarily beginners and students) that there is much less misunderstanding, because it is always clear that a certain node is meant.

I generally understand the desire not to use this kind of formatting in other posts, especially when it really is about code, or just to highlight certain parts of the text.

In the case of Geometry Nodes, however, we are dealing with a universe all its own.

There is no code here, there are no submenus scattered anywhere in the game, here we have a playground largely separated from all other areas.

The problem I see here is that in my experience the recognizability of input values, socket identifiers (inputs/outputs), and node identifiers are given too little distinctiveness if you don't allow formatting with backticks. Writing the name of a node in italics or bold is not a solution and only causes confusion.

For example, I do not distribute points on faces, no, I use the node Distribute Points on Faces. And if I mean a certain input of this node, then I write e.g. Distance Min. This is clearly stated in the universe of Geometry Nodes and does not get in the way of a nice line of code.

I ask for some thought and discussion here before another one of my posts becomes a victim of styleguide corrections and I have to revert these changes.

My goal is that the current style guide states: "Use backticks only to mark up code, or when you want to express a particular node.".

Another possibility I see is a new formatting tag, such as <node></node>.


I'll use a concrete example:

In this text I write:

  1. So that I can also control the rotation of the object, I use the Tilt property of the curve. However, so that the value defined via Group Inputs also always generates a rotation from one end to the other end of the arc, I use the node Map Range and feed it additionally with the value Factor, which the node Spline Parameter gives me.

Here you can see that I mean the Group Inputs, but not the node Group Input. I could of course write Group Input and Group Inputs, but the difference would then no longer be clear from the text in extensive descriptions.

However, writing a node in italics is not practical because it is quite possible to mention a node in an italicized text.

Here I mean the Node Cube, and not the Cube created before.

But i could write:

Here I mean the Node Cube, and not the Cube created before.

But bold text should not be used to highlight nodes, as this type of highlighting should rather mark places in the text that are of appropriate importance.


Furthermore, I write in the example above:

PS: I have hidden some of the irrelevant sockets to save some space. You can show them again with the key combination CTRL+H.

But I could also write:

PS: I have hidden some of the irrelevant sockets to save some space. You can show them again with the key combination CTRL+>H.

Or even:

PS: I have hidden some of the irrelevant sockets to save some space. You can show them again with the key combination CTRL+>H.

Why don't I do that?

Quite simply because a key is something that, although it is actually quite clear and understandable in the text, is a kind of marker and reading aid when someone is trying to follow instructions and filter out the essential steps from a text.

This has been common practice here for a long time, and it makes sense.

But now it's time to create such markers for nodes as well, since the existing stylistic means are not sufficient in my opinion.


Or a fictional example:

Create cubes with the Node Cube and instantiate them with Instance on Points at the corners of your cube previously created with Cube. Then instantiate them on the grid you created with the Node Grid.

It would be better to write:

Create cubes with the Node Cube and instantiate them with Instance on Points at the corners of your cube previously created with Cube. Then instantiate them on the grid you created with the Node Grid.


Here is another fictional example:

Plug the geometry from Group Input into the input Geometry of Group Output to make your geometry visible with Geometry Nodes.

Plug the geometry from Group Input into the input Geometry of Group Output to make your geometry visible with Geometry Nodes.


Summary

The Rules
Thanks to Duarte Farrajota Ramos for the wonderful picture!

In summary, the question "Backticks or no backticks?" can be answered with the following words:

The code is more "guidelines" rather than actual rules.

There are (especially here on Stackexchange) obviously at least two dominant camps of users:

  • One relies on structures and approaches that have grown over a long time and are generally considered proven and stable. This tends to be the logical type (I won't say "older").
  • The others (mostly younger users) are fast-moving and flighty and are used to "skimming" texts and are dependent on certain "markers" that, from their point of view, increase the readability or comprehensibility of a more complicated text. This tends to be more the visual type.

In fact, it's not about breaking or following rules, but about providing purposeful answers.

The solution is what matters, not the backticks!

So, strictly speaking, this question remains unanswered, but not because there are too few profound positions on it, but because we humans are simply too different to lump them all together.

Different generations, and different learning types, different cultures & perspectives.

And that's a good thing! Long live diversity!

$\endgroup$
1
  • $\begingroup$ Comments are not for extended discussion; this conversation has been moved to chat. $\endgroup$
    – Robert Gützkow Mod
    Jul 6 at 8:53

4 Answers 4

3
$\begingroup$

I think the current formatting is sufficient. Italics to indicate node names feels adequate for highlighting them, I don't think they deserve any further distinction from other UI elements like menu structures, panels, buttons or other interface components.

Contrary to what this question suggests, nodes have been around for quite a while, we've had Cycles Shader nodes for what feels like an eternity now, for more complex computations in the modelling area before Geometry Nodes existed we've had Animation Nodes and Sverchok, and long before all of them we've always had legacy Blender Internal Material nodes and Compositing Nodes.

I don't feel geometry nodes are any different nor deserve special treatment.

When I mentioned "the formatting rules" I probably used too strong a word. That was not what I meant, they are more guidelines than actual rules. enter image description here

They've been around for a while, far before I was even participating here, and we do tend to stick to them for consistency sake. You're free to follow them or ignore them (though we'd prefer if you stick to them), the same way other users are free to enforce them by suggesting edits. I never really questioned them because they seemed adequate, and judging by how consistently they've been used so far, and how this never came up before despite the visibility our edits provide, I'd say most users would tend to agree as well, or at least are not bothered enough to question them.

Now I don't feel strongly against using different formatting for node names, nor stronger highlighting. If we do decide as a community to use something different I'm all for it, but I still think using code ticks are too disruptive and potentially misleading so I'd go against that specifically.

As suggested by Campbell Barton backticks can be used for actual code or some times for values, but for node names may cause confusion with actual code, file paths, driver expressions or other truly monospaced data which may coexist in the same answers.

As moderators we don't have the ability to introduce new formatting markup or methods, that would require an accepted feature, and corresponding development and testing from the site administrators.

One possible alternative if you really feel any node requires further highlighting, and I may actually be useful and educational is using documentation links in node names like Curve Circle Node or Add > Geometry > Convex Hull in addition to Italics. This seems to create enough distinction and value, at the expense of extra work for the writer.

I wouldn't enforce it for the overhead it creates neither for answerers nor editors, but would certainly welcome users who went to the trouble of including documentation links in their post.

This has to be a community decision, I'm open to other suggestions, so lets see what others have to say about this.

$\endgroup$
10
  • 1
    $\begingroup$ I fully agree. The combination of italics with links to the documentation could be a good compromise that is fitting both our current style, provides additional information and has highlighting as requested. $\endgroup$
    – Robert Gützkow Mod
    Jul 5 at 10:46
  • 1
    $\begingroup$ So first +1 for the picture :D $\endgroup$ Jul 5 at 10:58
  • 1
    $\begingroup$ And you mean I should link every node now? That can mean quite a lot of additional work for me. I think the idea itself is not bad, but there may well be errors (and outdated links if I don't always link to the exact node of a particular Blender version). $\endgroup$ Jul 5 at 10:59
  • $\begingroup$ But I only partially agree with you. You as a moderator and other experienced users don't see it anymore, but for younger users and beginners highlighting node names provides a huge support. $\endgroup$ Jul 5 at 11:01
  • 2
    $\begingroup$ @quellenform No, as mentioned in the paragraph before the last it is a lot of additional work for both answerers and editors. So I wouldn't enforce it, even if the suggestion was accepted by the community, which it hasn't. The work it requires could be minimised by an extensive list of macros or snippets, but I wouldn't really want to maintain one either, so take it as a suggestion if you really really feel the need to highlight something very badly ;) $\endgroup$ Jul 5 at 11:04
  • $\begingroup$ So according to the number of current votes, I will probably have to include a lot (!) of links in the future ...but possibly that was also a very disastrous image choice! :D $\endgroup$ Jul 5 at 16:57
  • $\begingroup$ Well don't claim defeat yet thing may still sway the other way. On a more positive note, I'd be very interested if you curated an exhaustive list of snippets including node names and links to corresponding documentation. $\endgroup$ Jul 5 at 17:10
  • $\begingroup$ @DuarteFarrajotaRamos I'm afraid I don't quite understand: what exactly do you mean by "...exhaustive list of snippets including node names and links to corresponding documentation"? So you would be happy as a Mod, if in my posts actually links to (sometime outdated pages) to Blender documentation would find their way in!? Wouldn't that be a lot of work for you (or other moderators)? $\endgroup$ Jul 5 at 18:16
  • 1
    $\begingroup$ @DuarteFarrajotaRamos OK, let's wait and see what else happens.... By the way, I would also like to compliment you (This has to be said, although you are known to some as "The Spanish Inquisition" ;-): I find it positively outstanding how you are able to clarify your point of view without saying: "Your opinion has no place here and it's pretty crap". In the three months I've been here on BSE, I've observed a behavior that makes me doubt the competence of some people. Now I understand why you are a moderator. Thank you for your constructive suggestions and your responsible use of this platform! $\endgroup$ Jul 5 at 19:01
  • 1
    $\begingroup$ @quellenform not everyone agrees, but thanks for the kind words. And it would be the "Portuguese Inquisition" btw ;). As for the list of snippets it would look something like a list of *[Curve Circle Node](https://docs.blender.org/manual/en/latest/modeling/geometry_nodes/curve_primitives/curve_circle.html)* but for every node. Obviously I was just joking ;it would be a tremendous amount of work to do by hand, and probably pointless. Maybe an interesting challenge to write a script to scrape it from documentation, for it to be posted here in some canonical meta post $\endgroup$ Jul 5 at 21:05
1
$\begingroup$

I am more of a passive user in this part of StackExchange (reading posts only). I just read through all of this and very much have to agree with @quellenform that for new users its almost impossible to understand alot of the things written about Nodes. Not just Geometry Nodes.

Having an extra formatting available for them would be great. The post which was litterly linked here and blames about missuse of Backticks has a lot of informations about Backticks and that they are quiet often used for other things than code as 0.5 Numbers or telling where to find options File > Settings > Window > Mode. Also for keys to better differentiate between l and I.

Me as a fairly new user in this area can hardly ever understand post about Nodes because of bad formatting and have to read the same part 2-3 times. This post here I understood the first time reading it.

I understand that having an extra formating as html tag would not fit the html rules but it is fairly often used to have an addapet version of Markdown in use. Even Subscript, Stroked, underlined or Superscript was not always 100% default Markdown Syntax (sad enough <u> does not work here) and in some Editors have to be enabled first. Still they are widly used as ~sub~, ~~stroked~~, __underlined__ and ^superscript^. Sometimes they may have slightly different chars as marker but they still are part of a Markup language just maybe not the 100% default Markdown.

What I am trying to say is, that one could just add a new type of char that then translates into some html tag or html div box with inlinestyle. I understand that the div box may not be appropiate but a standard would be to have ==highlighted==. Which is fairly widly used and still does not exist here on StackExchange.

I think having some more options to style your questions/answers easly would be very helpful and would lead to less "Wrong" Styles.

I know these were not needed the early days but we have alot more technical things to talk about today than we had some years ago. In that way also the ways to Style your questions may have to adept to the greater amount of information, technics and problems we have today.

$\endgroup$
6
  • 1
    $\begingroup$ The moderators of Blender's Stack Exchange are not employees/developers at Stack Exchange, Inc. We are users that have been elected by the community and as such we cannot implement new formatting options. What we can do at most is set guidelines how the existing formatting options should be used and edit answers accordingly. $\endgroup$
    – Robert Gützkow Mod
    Jul 5 at 14:44
  • $\begingroup$ @RobertGützkow I am very well aware of that but having enough users - and esspecially well known users - that want a change in something should lead to the point where the developer team decides to bring wished changes. As w developer I know such things dont change from one day to the other but as a developer I also know how little work it would be to add a formatting option, document it and release it. $\endgroup$ Jul 5 at 14:48
  • $\begingroup$ @RobertGützkow Besides that what I mainly wanted to say is that I think allowing Backticks for certain things would be very useful if no other way of formatting is provided. And in my - most likly many peoples opinion - having only 4-7 ways to format (yeah you can combine them I know) is not enough. I am speaking of: Italic, Bold, Backticks, Links. Cuz the other options as Tables or <sub>subscript</sub> are not very viable in comments anyways. $\endgroup$ Jul 5 at 14:52
  • $\begingroup$ @AtLeastVision That sounds very ambitious! But as far as I know, here on SE a RTE from the stone age is used (WMD, lightweight/stable), and RTE is not only about usability, but always also about security. Theoretically it might be easy to implement, but probably nothing will ever change there, because it costs money and (at least from the site owner's point of view) doesn't bring significant benefits. I think granting the possibility to extend the use of formatting is the only viable way for now. But hey, who knows, maybe you'll send an application to SE and they'll hire you as a programmer!!? $\endgroup$ Jul 5 at 15:15
  • 1
    $\begingroup$ @quellenform looking at how much they work on features I am very sure I do not want to be part of that developer team. I know secuirty is important but adding more formatting options should not change anything in terms of security and if it does they may just overthing the code they created :/ $\endgroup$ Jul 5 at 15:24
  • $\begingroup$ @quellenform It may not be beneficial in terms of money in the other hand it shows users they are still working on things they want to have which should be beneficial in some ways too. Also giving the possibility - as other sites do - to contribute your self would be more beneficial for them than anything else. $\endgroup$ Jul 5 at 15:27
1
$\begingroup$

This is a bad idea for at least these reasons:

  • Perversely, adding typographic styles to text often makes it less readable: It's hard to use consistently and used inconsistently leads to confusion.

  • English has had a convention for such situations for at least 100 years and it is called out in most style guides, especially those used for technical publication. If you have 'foo type A' and 'foo type B' and you need to disambiguate you either

  1. Always specify the second part of the phrase; or
  2. Specify in advance that if the second part is left off it always means 'type B' and always specify the second part of the phrase for 'type A'.

Here are two contrived examples:

Now we apply the cube node to the cube object and see that the cube object has been transformed by the node.

Now we apply the cube node to the cube and see that the cube has been transformed by the node.

  • This is the convention followed in the Blender manual and I'd score 'consistent with manual' much higher than 'another convention to learn'.

  • Meanwhile text is reserved in technical stack exchange for code and other computer text to simulate what the text would look like on a monitor. I think it's a bad idea to overload that meaning with what amounts to an attempt to use bold text.

Aside: The manual uses ModifierKey to signify that a key is typed while a modifier is used. I prefer this endash format over other ways of tying the modifier to the key for consistency; and wish that were part of our standard.

$\endgroup$
12
  • 1
    $\begingroup$ The - I will call it "English Convention" is nice to have do not get me wrong. But having a lot of text and complicated stuff to explain it is much easier to actually have less text and better designed. There is a reason graphics work better for explenations than text. Formatting is the closest we can get to have "Graphical Text". So giving formatting a appropiate and standard meaning is much more appropiate than "just write something behind it". Because as fast reader you may skip suffix or prefix but you will not skip a formatting because... well you litterly cant overlook THIS or That $\endgroup$ Jul 5 at 18:35
  • $\begingroup$ Typography rarely works better than text consistency. Text book publishers have studied the use of typography a lot, and they've found that typographic conventions using visual weight tend to cause people to skip over and ignore other text. The result is that you get different confusion when visual weight is used but usually more readers are confused rather than fewer. The idea of using visual weight has ben reintroduced about every ten years since the 1950s, so this proposal isn't even a novelty. People like it for a bit, but it tends not to work and is discarded fairly quickly $\endgroup$ Jul 5 at 19:43
  • $\begingroup$ It may work better for plain information which is complex by it self already. Even then having examples as graphics and in that way text which is more graphical than just plain text is not only much more appealing to read (essepcially for younger people) but also easier to skip over and get the information needed. Obvioulsly formatting is a skillset to and using it properly is a part of creating a good question/answer which if used correctly provides a more friendly studing experience. Having a book with 100 words and no graphics is a type of book a teen will neever read if not rly needed. $\endgroup$ Jul 5 at 21:08
  • $\begingroup$ No, having text that is more graphical is not more appealing to read, not even to younger people. This theory has been proposed at least once a decade for 60 years, tested, and rejected. Yes, it is easier to skip over information. But the consequence of that turns out to be the opposite of what you suggest. Note, I am limiting this to visual weight in typography. Additional graphics is an entirely different matter, and not what is being proposed here. $\endgroup$ Jul 5 at 21:27
  • $\begingroup$ And frankly, you do teens, who devour young adult novels with no graphics, a disservice by asserting that they will not read text-only material if not needed. Again, we're talking typography, not additional graphics, in this setting. $\endgroup$ Jul 5 at 21:31
  • 1
    $\begingroup$ The Problem is I can speak from personal expirience and expirience from people in my university. Texts with no graphical processing are not appealing for a younger audiance. Please go ask 10 students and 8 of them will tell you that. (the other 2 study law xD). Its simple as that nobody likes to read 5 sites of text. But having a decent typography makes it much better to read because the author can mark important areas and the reader then can read them and if he is interessted or needs more information can read it again. That just how younger people tend to read. $\endgroup$ Jul 5 at 22:03
  • 1
    $\begingroup$ Just because you seem to like to read 10 sites of plaintext documentation does not mean everyone does. If Typogragphy is so bad and not used for 60 years and each decade again deneid why does everyone use it in their posts. Why do adds have special rules for it so the reader reads a certain part faster and is more appealed. Why do modern study books use it? Not every brain works the same ofcourse but as I stated already. Most younger people today grew up with the media world and can find things here much more easy than older people may find in a library. $\endgroup$ Jul 5 at 22:06
  • $\begingroup$ Technic changed so much over the last years and so did our basic understanding of design, simplicity and so on. ANd what I meant with graphics btw is not that you have to use graphics. I was speaking of transforming text in some kind of graphic because thats what Typography is about if you ask me. You make text more appealing and easier to differentiate certain things. $\endgroup$ Jul 5 at 22:07
  • $\begingroup$ Typography is not bad, but the way its being proposed here has been shown over and over again to cause more problems than solutions. You hit the key issue: adding visual weight causes people to skip over information and become confused. This isn’t about what I like; it’s about what practice has show works and doesn’t. Mixing type multiple type faces doesn’t work. It creates visual clutter and confusion. The rare use of typeface change for emphasis works until the use becomes common. Using bold the first time you introduce a term is good practice. Using it on every occurance dilutes value. $\endgroup$ Jul 5 at 22:54
  • $\begingroup$ Typography is far more that what you call ‘graphics’ but a typographer would call ‘frequent font switching. It’s about line length and word spacing and kerning and so forth. Nothing about changes in Blender justifies adding the degree of visual clutter being suggested here — a degree that is well understood to make text less readable. $\endgroup$ Jul 5 at 22:57
  • $\begingroup$ I see Typography as a form of graphic. You may or may not like it. But in the end letters are just graphics we gave a special meaning and Typography is the placemant and art of it. As I stated I think having a little more styling opotions esspecially styling options hwere the style fits the purpose dependign on the stackexchange you are on would be very useful. I see you dont like the idea of skipping text at all. That is... sry to say it like that... a "You Problem". You may not like it but in a worl of rush as we have it today it is needed. But lets talk here in the chatroom $\endgroup$ Jul 5 at 23:04
  • $\begingroup$ chat.stackexchange.com/rooms/137558/… $\endgroup$ Jul 5 at 23:04
0
$\begingroup$

So as Duarte Farrajota Ramos recommended, here is my suggestion so this can experience votes:

Bold and italic are essential for formatting text and giving certain words a specific meaning. They are not an option for highlighting nodes.

What is not an option is:

  • italic
  • bold
  • underlined
  • Key

Which sounds interesting, but is not practical:

  • linked
  • other highlighting that would require HTML code

What might get in the way of code:

  • Backticks

But since in the universe of Geometry Nodes usually no paths, code fragments or things are used, and if then only in absolute exceptions, only one possibility remains: Backticks.

So, since there is no single way to format a node differently, my recommendation is:

Use backticks (`) to delimit a (geometry) node as such from the text

...but avoid it if it is not really necessary

This allows to distinguish Cube from Cube.

But the irony of the whole story is: Those who would benefit from the better readability and subsequent comprehensibility don't even read (and vote) these meta posts, but it's only those who make the rules anyway or are already so familiar with all the stuff here that any irregularity immediately catches their eye...

$\endgroup$
1

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .