Documentation clarity

[mirogeorg]

Hi Franco,

First of all, I want to commend you for creating and maintaining the zpaqfranz project. It's a valuable tool, and I appreciate all the effort you've put into it.

I was going through the documentation and found that some sections were a bit challenging to understand. I believe that enhancing the clarity of the documentation could make the project more accessible .

Suggestion: Consider using ChatGPT or similar language tools to help rephrase and refine the documentation. These tools can assist in making the content more fluent and easier to comprehend without altering the technical details.

Clearer instructions and explanations can help users better understand how to use the tool effectively. Tools like ChatGPT can save time by quickly generating well-structured and grammatically correct text.

Thank you again for your hard work and dedication to the project!

[fcorbelli]

Writing documentation is essentially pointless. Sad, but true. Almost no one reads it. If you make it detailed, meaning you explain things thoroughly, it becomes extremely long and complex. If you just add a few notes, it remains rather useless. I understand well that it's a small hobby project, and I usually respond in detail to those who ask specific questions. For example (talking about the latest development), I could write a great explanation about using zpaqfranz on a Cortex-A55. These are ArmV8.2-A CPUs, with the "2-A" being the tricky part. Basically, binaries compiled for Arm v8 don’t work (aka: Annapurna based QNAP/Synology). You have to go through quite a process to get a Cortex-A57 binary, which is compatible. What’s the purpose? To use zpaqfranz on new generation QNAP Arm NAS devices. How many people could be interested? I think very few. In fact, probably none. 😄

Short version: no or few users => no feedback => no or little effort to improve documentation.

Even just passing a hundred pages to ChatGPT means working for days. I'm so unmotivated that I leave bits of code in Italian in the source. Who cares anyway?

[fcorbelli]

A strategy I had thought of was to outline different scenarios with the best suggestions. If you have a Windows machine, do this. If you have a Linux server, do that. Want to do a cloud backup from a Windows machine? Do this. Need to verify copies? Do that.

But realistically, how many people would not only read them but actually put them into practice?

Some time ago, I wrote an incredibly detailed guide on how to do backups in the professional world. I mean, where they pay you thousands of euros. I posted it for free on the FreeBSD forum. The usual immature user (aka: a bimbominkia) started a flame war. I deleted everything. In Italy, we say “dare le perle ai porci"

So if a user needs something, perhaps reporting bugs or asking for clarification, he open an issue, and I respond. Over time, I’ve addressed (almost) all of them. The only thing missing is zpaq over TCP, but that's a very big task, and I’m not getting paid at all. Anyway, I’ll do it sooner or later. If I seem a bit unmotivated, keep in mind that, just to give you an example, it’s been THREE YEARS that I’ve been trying to get zpaqfranz included in Debian. The “sponsor” handling it typically dedicates half a day to it EVERY YEAR on August. I don’t know why he thinks zpaqfranz needs to become some kind of amazing super duper mega software, better than any other Debian package. I see software getting published that is, to say the least, flawed. But that doesn’t apply to zpaqfranz. The level of nitpicking is unbelievable. If this level of scrutiny were applied to every part of Debian, Windows would shut down tomorrow. Actually, maybe even by tonight.

Anyway, just a bit of evening complaining 😃

[mirogeorg]

Franco, we are all very grateful for the efforts you're making. This post is just an idea: perhaps you could run your texts through ChatGPT, or even write them directly in Italian and let ChatGPT handle the rest—word order, style, and so on.

Otherwise, we are reading the documentation ;) It's difficult to gather all the information from the forums and other channels where you write. The more examples you provide, the clearer everything becomes.

See, for example, how ChatGPT can format your two posts to make them easier to read. I'm Bulgarian, and our sentence structure also differs significantly from English, and sometimes the meaning gets lost, even though you're reading the words... So I completely understand you, and these advancements in artificial intelligence can help us.

Summary:

The author expresses frustration with writing documentation, feeling it's often pointless because few people read it. Detailed documentation becomes too long and complex, while brief notes are unhelpful. They usually respond directly to specific user questions. An example involving zpaqfranz on Cortex-A55 CPUs illustrates the complexities that few might appreciate. Due to minimal user engagement and feedback, there's little motivation to improve documentation.

They considered creating guides for different scenarios but doubt many would read or implement them. A past experience of sharing a detailed professional backup guide resulted in negative reactions, leading them to remove it. Now, they prefer to address user needs individually when issues are reported. The author is also disheartened by the prolonged and overly critical process of getting zpaqfranz included in Debian, especially when other flawed software gets accepted more readily.

Rewritten Text:

Writing documentation often feels futile because hardly anyone reads it. If I make it detailed and thorough, it becomes excessively long and complicated. If I keep it brief, it ends up being unhelpful. Given that zpaqfranz is a small hobby project, I usually provide detailed responses to users who ask specific questions.

For instance, I could write an extensive explanation about using zpaqfranz on Cortex-A55 CPUs, which are ArmV8.2-A processors with some tricky compatibility issues. Binaries compiled for Arm v8 don't work on these CPUs (like those in Annapurna-based QNAP/Synology devices). To get it working, you need to compile a Cortex-A57 binary. However, I doubt many people are interested in using zpaqfranz on new generation QNAP Arm NAS devices—probably very few, if any.

In short, with few users and minimal feedback, there's little incentive to improve the documentation. Even using tools like ChatGPT to process the documentation would take days of work. I'm so unmotivated that I sometimes leave bits of code in Italian within the source code because I feel it doesn't matter.

I had considered outlining different scenarios with best practices—for example, instructions for Windows machines, Linux servers, cloud backups, or verifying copies. But realistically, how many people would read and implement them?

Some time ago, I wrote an extremely detailed guide on professional backup strategies, which could be worth thousands of euros. I posted it for free on the FreeBSD forum. Unfortunately, an unappreciative user started a flame war, so I deleted everything. It felt like offering pearls before swine.

As a result, if a user needs something—like reporting bugs or asking for clarification—they can open an issue, and I respond. Over time, I've addressed almost all requests. The only feature still missing is zpaq over TCP, which is a significant task, and I'm not getting paid for it. I'll get to it eventually.

If I seem unmotivated, consider that I've been trying for three years to get zpaqfranz included in Debian. The sponsor handling it typically dedicates half a day to it each year in August. He seems to expect zpaqfranz to be exceptionally perfect, beyond the standards of other Debian packages. Meanwhile, I see other software being published despite flaws. The level of nitpicking is unbelievable. If such scrutiny were applied universally, even major systems might fail.

Anyway, just sharing some evening thoughts.

[fcorbelli]

Sure, here's the translation of your message into English:

---

I understand that you're trying to find a polite way to say that my English is terrible, but — actually — it's even worse than that. As mentioned, with no real incentive, I usually write during the downtime while waiting for compilations, so my brain is probably only about 5% engaged. I put more effort into Russian, but my accent is really terrible.

Anyway, regarding the documentation, if you know a way that "magically" allows ChatGPT, or something like it, to load Wiki pages ON ITS OWN and organize them ON ITS OWN, that would be great. The problem is if, for each page, I have to go in, copy, paste into the LLM, take the response, paste it back into the wiki, and move on to the next page. Not to mention that, since we're dealing with sometimes very "sensitive" topics, it's still necessary to proofread and correct, because ChatGPT can't always fully understand which parts are irrelevant and which are not when dealing with these topics. So it's not even enough to just write in Italian and have ChatGPT translate (I've tried that for a while), you still need to "refine."

But the problem is something else. More than the "how," it's the "what" to write. Incidentally, I see that other similar programs sometimes have documentation that's completely absent or worse than mine (!), which isn't easy. Unfortunately, thinking that a "manual" must necessarily be "easy" is utopian if the program is extensive. The Word manual, for instance, can't be just 5 pages long. That would be nice, but it's impossible. A "real" manual would probably be about 5,000 pages. But who would read it?

Back in the days, there used to be paper manuals, I bought a couple, maybe 30 years ago. But they're gone now. No one reads them. Not even online help exists anymore. Those things are from the past. Whereas an LLM like zpaqfranz, a kind of "superbot" where you ask a question and it gives you an answer, would make sense. But electricity in Italy costs too much (!) to train my own little llama (I had actually thought about it, to be honest).

If, on the other hand, I had a number of users asking me, "what's the way you recommend for doing this thing?" then I could make the effort. There are details in zpaqfranz that are unique, like the large text. Why the large text? Because if you have very long logs, the large text immediately makes the results stand out.

[fcorbelli]

Here you can find some "spiegone"

https://github.com/fcorbelli/zpaqfranz/wiki

But I dubt that someone will ever read 😄

[197788]

Here you can find some "spiegone"

https://github.com/fcorbelli/zpaqfranz/wiki

But I dubt that someone will ever read 😄

You can even git clone the wiki, which is what I've done. Easier to open the individual markdown pages in a markdown reader than having to go to github all the time. Thank you, Franco. I like zpaqfranz a lot!

[mirogeorg]

You're doing a great job, and we really appreciate your efforts.

Maybe I didn’t explain it clearly. My suggestion is simply to use ChatGPT to refine the English phrasing for clarity, rather than restructuring the content entirely. The priority here is to minimize the effort involved.

Regarding the documentation, I’d say this: it would be beneficial to include more examples. For instance, the answers you provide on the GitHub Wiki—just add them to the documentation as well. Even if it's not perfectly organized, examples are extremely valuable and often speak for themselves.

An even simpler approach would be to include references in the documentation to the issues section on GitHub.

Of course, this is just a suggestion.

[fcorbelli]

My suggestion is simply to use ChatGPT to refine the English phrasing for clarity

It is already done 😄 The problem is that even ChatGPT does not know exactly what to write, sometimes taking flights of fancy and making up switches (interspersed with --) that do not exist If you take a portion of English, give it to ChatGPT and tell him to correct it, it will come out even worse, when it comes to these kinds of topics

What would be needed are volunteers to edit, correct and expand the wiki But they don't exist

Regarding the documentation, I’d say this: it would be beneficial to include more examples.

They are already here (the example). In the executable You can find newer options, just looking for newer examples Just about every single "thing" does have an example Why? Because the very first thing I do, after adding some function, is to add an example in the relevant help So it is virtually impossible to have a new feature without an example. I don't know exactly how many, I think about a hundred. Maybe more

[fcorbelli]

The two points I'm working on are profiling memory usage, dividing it between what is allocated on the heap by threads, what is in arrays, and what is in the DT. To determine the best way to proceed. OK. But what are the differences? What is the DT? How do I minimize its use? Why should I do that? When should I not care? Why isn't there a universal method? And so on and so forth. In short, an in-depth explanation of what -frugal does (within the add command). But ChatGPT doesn't know. Unfortunately, you can't ask it to "explain how DT works inside zpaqfranz". Maybe in the future, who knows?

Sure, I could have it explain the other part, like what Hyperthreading is. However, it doesn't know the connection between it and the memory used by threads on the heap. There, I’d have to explain it myself—or not. If "not," then people struggle to understand why I'm working to remove Hyperthreading by default. At that point, though, it should be kept in "CPU burner" mode (i.e., benchmark -all). Basically, if you take a text in Italian and give it to ChatGPT, you'll get something like what you're seeing now. When I have time, I correct it myself; when I don't... I just don't.