You are viewing archived messages.
Go here to search the history.

Jason Morris 2023-02-28 06:11:22

What do you do to motivate yourself to update documentation? I have so much of it that it is now a significant undertaking to keep it up to date with the tool, and I am losing interest. I'm trying to figure out whether I should just tag most of it as out-of-date and come back to it later when there are enough users to justify it...

Jarno Montonen 2023-02-28 06:56:38

My complete lack of motivation for updating documentation makes me very motivated to find solutions to minimize the amount of documentation needed.. 🙂

Lu Wilson 2023-02-28 07:00:05

I don't know the context here, but I can throw out some thoughts:

  • Writing docs forces you to spell out how your project works and what it does. It can help to deepen your understanding, and highlight confusing areas. Even if nobody reads it, it can be a helpful exercise.
  • It's ok that docs aren't perfect. Sometimes there are other things to prioritise - so raise an issue on the repo like you would with any other bug. This can also help to prompt help from other people down the line.
  • There are lots more docs generation tools nowadays that might help speed up the process.
  • "What comes first - the users or the docs?"
  • A lot of docs are very dry - can you make them in a format or style that's more fun for you?
  • What kind of docs suit your project best? To-the-point reference? Just some examples? A tutorial? A blog post?


someone who loves writing docs

Paul Tarvydas 2023-02-28 09:56:04

FYI - brainstorming - I’m playing with Obsidian (markdown) and Descript (video editing) and Just Press Record (AI transcription of audio), searching for ways to reduce the boringness of creating documentation after-the-fact. On my wishlist to understand better: iMovie, Da Vinci, OBS, Loom, “howto interview” (towards “interviewing myself” to get technical points across), etc, I’m also playing with drawware (tech diagram compilers) to reduce the need for documentation.

Eli Mellen 2023-02-28 12:29:43

<puts on professional documentation person hat>

I think a key to most great documentation is that it does 1 of the following, and doesn’t try to be everything for everyone all at once. It picks a lane, and runs with it:

  • Tutorials, learning-oriented (teaching someone to cook)
  • How-to guides, problem-oriented (a recipe for cooking a specific thing)
  • Explanation, understanding-oriented (historical overview of an ingredient’s cultural importance)
  • Reference, information-oriented (an encyclopedia article about an ingredient)

Each of these types maps fairly well to an audience:

  • Tutorials are for folks who are totally new to a thing
  • How-to guides are a step up from tutorials and help you learn idioms and best practices of a space
  • Explanation is useful when needing to convey the value of a thing
  • Reference is generally for experts who are cozy doing the thing

When you are writing your docs., are they really descriptive? Do they have a specific audience(s) in mind?

Having a clear idea of your “ideal documentation reader” in mind, can help keep them manageable, since it can let you focus on not having to documenting everything and instead just what’s needed for your goals.

</doffs documentation person hat>

Jason Morris 2023-02-28 18:33:50

Wow. Exceedingly helpful replies, everyone, thank you. My documents happen to be divided more or less exactly as you suggest, @Eli Mellen. And Paul Tarvydas I'm using OBS, and getting into gifs, because the tool is so visual. Lu Wilson I'm going to see if there's a way to have more fun with it! Thanks for the suggestions!

Niall McCormack 2023-03-01 21:03:09

What's the general consensus on node based scripting?

I'm intrigued by Unreal's Blueprint node based scripting tools - they seem easy to use, but if you want to do anything complex then (for me) it becomes very messy very quickly. However with the general move in the past 10 years or so to more functional programming and serverless etc then perhaps it makes sense. Small components that can be wired together visually feels easy , or right ?

Darklang is another example with extrapolates the complexities of the underlying system allowing you to just write some pseudo node based (at least when I last looked at it) components that are easily wired up together.

I'm an iOS engineer by trade, and it feels that something like Darklang / node based coding could end up matching nicely with SwiftUI's declarative syntax for UI.

Michael Gummelt 2023-03-01 21:27:21

The main benefit of node based programming, or "node and wire", in my observation, is that is saves users from parsing. Mentally parsing code into an AST is difficult. It requires literacy. Node-and-wire makes the parsing explicit.

The downside is that reading and writing the graph is much less efficient for a literate author.

William Taysom 2023-03-02 08:16:14

If it's just parsing, then block-based or structured editors should have the same advantages.

A potential advantage of a node system (though maybe not realized in practice) is using layout so that some conceptual aspect of the system is well modelled: often nodes below depend on nodes above. Compare with the text of say imperative programs text in which conditional branching gets squished and functional programs are often worse with the conceptual reduction tree split up across lots of definitions.

More than anything, I think node based systems have extra space to interweave intermediate results with the authored scaffolding.

Niall McCormack 2023-03-02 13:46:36

I wonder if it also makes you code in a different more modularised way. Smaller chunks of code rather than sprawling classes. It’s a mindset shift of course, but it may make your code “better”

Vijay Chakravarthy 2023-03-02 17:55:57

We have been building a live programming environment with a node based visual model for the last 6 years now. There are a few advantages which text based systems dont have, IMHO:

  • Reuse by bringing in visual blocks that are prebuilt.
  • Unified interface for multiple aspects such as for performance, debugging, inspection of state and live values along with programming.
  • Zoomability (we are not yet doing this) : Different tiles can have different levels of zoom, and that can make for a very interesting interface.

We have built a good number of production apps using our own platform, so the pros and cons of the approach are quite well understood by us. For things that are assembly oriented (composition by reusing work done by others, I think visual programming is quite elegant). For algorithmic thinking it would need to be augmented with other modes (in our system you can write new functions in any language that compiles to wasm, plus also write web components and bring them in).

Ibro 2023-03-03 01:06:28

+1 to what Vijay said about modularity and reuse. Generally a smaller command set means more distinction between elements (different colors and shapes for values, functions, math). Dragging out a node highlights where it could go and “type errors” if connected wrong. That’s more difficult as an environment becomes more open (less predictable ).

Unreal’s primary target has been large game studios, where there are often developers writing algorimic code but outputting nodes to be tuned by other teams. Bolt is an interesting example where both happen at the same time.

None of this is unique to nodes; though they might give a better spatial view

Jarno Montonen 2023-03-03 06:20:46

I think the main benefits of node based programming is in control and data flow readability, debugging and live programming. It's natural to fit in rich node visualizations like does. However, I feel that you'd always want the node based language to be domains specific. Just projecting a general purpose language to nodes leads to too large graphs, low productivity and bad maintainability. And you should always be able to type in arithmetic expression. Much easier to read and type " 1 + 2 * 3" than have 5! nodes on the graph. Actually I think that it would be best for text to be the primary editing tool, but then have a generated graph for visualization and debugging.

Ibro 2023-03-03 07:45:14

I should mention, there were also a lot of interesting thoughts from a similar question I had a few days ago 💬 #thinking-together@2023-02-20T12:41:16.997Z. @Niall McCormack

[February 20th, 2023 4:41 AM] foc214: I’m curious “where” people think of visual in visual programming being. For context, I spend a lot of time in tools like Houdini, Solidworks, Cavalry, and After Effects. Some of them have more access to computation than others, but the biggest difference between those and Processing or threejs is a large “standard library” of functions. On the other hand, building a website with live feedback or scripting in a REPL seem like a very different experience from just writing the same code in notepad. I wonder if visual programming is all just “debug views” rather than the specific presence of a GUI. And if so, what does that mean for generalized visual languages or environments?

Paul Tarvydas 2023-03-03 19:50:18


Brainstorming, half-baked...

I would have ignored Ceptre in the past. It claims to be a language for writing games. The very idea makes me yawn. But, one of the guys at the Torlisp monthly meetup is deeply into robotics and Scheme and another guy, in the film industry, uses Racket for hobbying in game programming. My own interest is in concurrency and simplicity and compiler-writing. These fields are all related. Watching the 2015 Strangeloop presentation about Ceptre piqued my interest. Ceptre is logic programming, but with a twist - it has a built-in notion of explicit ordering. I thought that I could knock off a better game language using my diagrams of state machines. I continued to learn about Ceptre. Aside: Ohm-JS has built-in explicit ordering and is “not” context-free. I have to wonder if Ceptre is to generalized formalism as PEG (Ohm-JS) is to context-free grammar formalisms.

Dunno yet.

FYI, I watched the Ceptre talk. I then read the paper and now am reading the thesis. And in the background (foreground?) I am trying to convert Dungeon Crawler (.ceptre) into PROLOG. I think that Ceptre can be simplified down to a small handful of primitives which are easy to express in PROLOG or Lisp or JS or ..., but they are not the first thing that you think of when programming PROLOG. From there, of course, I would expect to generate code for Dungeon Crawler in Lisp and JS and Python and …

In the back of my mind is the question “Is This Steam Engine Time?” (Paul Morrison). Are we seeing a shift away from single-threaded languages (Python, JS, Rust, Haskell, lambda calculus, etc.) to ???. Certainly, hardware in 2022++ is drastically different from hardware in 1950 and we should be finding better ways to cope with this New Reality (“The Great Reset in Computing”)…

FYI: The drastic difference in hardware is the reality that we now have cheap CPUs and cheap memory. Both of these notions were completely unimaginable in 1950. Instead of crushing our hardware with bloatware like Linux, we can simply throw rPIs at a problem, each running single-threaded programs. There is no need to fake out multitasking anymore. Multicore is just a clumsy way to bridge across the two drastic realities, i.e. to force-fit 1 CPU programming languages onto many-CPU-programming. In fact, we shouldn’t even call CPUs CPUs anymore, since there’s nothing Central about them. Early adopters of 1950s computing built games. Maybe early adopters of 2022++ computing will build new kinds of games with 1,000s of PUs, for example 1 processor for each player and for each NPC.

Ceptre: [ 💬 #linking-together@2023-01-25T02:38:24.225Z

Call/Return 💬 #thinking-together@2023-01-22T14:06:36.762Z

I have not investigated this, but it, too, appears to be barking up the same tree:

FBP (Flow Based Programming)

Rafi Khan 2023-03-03 20:24:59

Very interesting line of thought.

The first quote in the flow based link "The real world is asynchronous: don't try to force everything into a synchronous framework derived from the architecture of early computers."

as well as your thoughts around cpus not being central anymore and cheap cpu/memory...

I think they all really do follow on what you're highlighting as the death of single threaded programming languages

Rafi Khan 2023-03-03 20:27:48

You see some things which aim to make multithreaded programming or concurrency easier in programming languages, but I do want to agree with your thought above about a fundamental foundational shift.

I think the capability for change (better hardware and more cumulative experience in designing software) is already fulfilled.

I guess the industry is just a lot slower to change.

I think another thing is that if there was more of a p2p design in software systems then we might spend more time thinking about systems along what you said of multiple rpis. But the centralised way in which much of the end-user software is delivered may not be as favorable for these less central designs of computing?

Paul Tarvydas 2023-03-03 21:42:59

Thanks for your comments, and causing me to think / clarify!

Trickle-down: I think that industry doesn’t adopt the current solutions because developers haven’t really solved the issues in a palatable manner. Developers haven’t solved the issues in a palatable manner because developers think that the issues are difficult. Developers think that the issues are difficult because they don’t have the language for dealing with such concepts easily. Developers are bought into the Silver Bullet of Functional Programming which helps them deal with fancy calculators but shoots them in their own feet for other kinds of problems. Real Physicists deal with this kind of thing by inventing new notations. Software developers have been coerced into thinking that there is but one notation (all popular programming languages are based on functions).

Rafi Khan 2023-03-03 23:05:09

Makes sense! I forgot to think about that.

I wonder how does one go about building the tooling and ecosystem around these new ideas? Developer tooling is expensive to build but harder to monetise?

About the inventing new notations, I really love that and the reference to physics. I wasn't aware that they did that... but thinking about DSLs and how we seem to invent new languages or libraries (pseudo DSLs in my book) when there is a vastly new domain in computing... it connects a lot of dots for me

Rafi Khan 2023-03-03 23:05:26

"Software developers have been coerced into thinking that there is but one notation"

This part really makes me sad, and I want to do something about it

Paul Tarvydas 2023-03-04 13:11:56

“This part really makes me sad, and I want to do something about it”

I would be happy to expand, if you want to tolerate more bloviation from me...

Rafi Khan 2023-03-04 21:46:17

Yes absolutely, eager to learn more