[DeanRoddey]

This is the kind of positive response that makes me glad I did this.

There's LOTS of descriptions out there of what ORBs are. I have a good video about how it works and what it does. I can't put ten books worth of explanation in a read me.

[corysama]

I don't need a book. I just need something. The word "ORB" is not even present in the GitHub readme. You don't link your blog or your videos. You know that the explanations are sitting there waiting for me. I don't and you didn't tell me.

Here's a positive suggestion: In the GitHub readme, lead with the second paragraph. The first paragraph is not important to anyone but you. Having it as the project's intro makes you come off as a self-important wank.

Cut the first paragraph and the first sentence of the second out completely. Cut the third and forth paragraphs as well. Keep the fifth "Because it doesn't use the STL" paragraph, then skip straight to the Goals section. Rewrite it to explain itself in concrete, positive assertions instead of what it's not and what it's anti.

Portability should come next. Then Gotchas. But, Modern vs. Classical is mostly a rant that doesn't help me understand your project. You've already heard more than enough about the license :p

You've made something really cool. You have every right to be proud of it. But, other people don't know how cool it is and they never will if you don't improve how you communicate with them. It's not just a matter of stating the facts. It's understanding their point of view and tailoring your communication around that.

You are a busy person. You know that there's more stuff being published every day than you could possibly even glance over. And, you know that most of that stuff is useless crap created by self-important wanks. So, what would it take to get you to invest the time to understand some random wank's project?

If you are like most people, you aren't going to sit down with a cup of tea and read the backstory of some random project like it's a New Yorker article. You are going to read the first paragraph, then briefly skip around the rest of the doc before deciding to move on or not. It's the only efficient way to filter through the fire hose of crap.

When writing your description, you need to respect the reader's time and ignorance. They don't know the huge amount that you know. They especially don't know why this project is worth their attention. Your job is to sell them on your project by being as clear, concrete, brief and genuine as possible.

[DeanCIDLib]

I'll take another shot at it.

But on the ORB thing, wires got crossed there. There's no way I'd mention the ORB in the read me. That's very important but small piece of the overall thing. He was referring to some of the videos on my personal Youtube channel where I talk about some of the technologies I've created as part of this project. Some of them are related to the ORB.

Obviously, if you have never heard of an ORB before it might take a bit of effort to understand. But I can't really explain in-depth the foundations of technology concepts in a video. I can only give the basics and demonstrate how I've implemented that technology.

Beyond that, it would require a bit of study on the reader's part, as it does for pretty much all libraries of this type. Qt's 3D graphics docs probably don't include a fundamental tutorial on modern graphics architectures, right?

[corysama]

Again, it doesn't need a book. Apparently the ORB feature is important enough that it has been mentioned many times in the discussion of this project. But, it's not given a single mention(note1) in the 1946 word description of the project.

I'm trying to get across is that you need to figure out what makes this project valuable from the point of view of the user and broadcast that loud and clear.

"It is a complete environment with build tools, project definition language, loadable text system, a virtual kernel to isolate it from the underlying OS, up through a full set of 'standard libraries', wrappers around lots of common functionality, UI framework, Object Request Broker and IDL compiler, VM based OO macro language with IDE, custom implementations of many standards (XML, PNG, ZLib, JSON, SMTP, HTTP, etc...), and lots of other functionality."

That tells me what this project is. [note1]Hey! Object Request Broker was even in there and I didn't see it in all the noise. Make that paragraph into a bullet list. It's really the most important part of the whole doc. If you have videos, other docs, link them right there. That way a visitor should be able to get a high-level impression of the project a glance. Not after interpreting the entire doc as a holistic concept.

All of the backstory, theory, goals, etc... are only interesting at all after they know that what they're dealing with and that it is actually worth investigating. Then, after they're invested in the project, they might have motivation to go elsewhere to read up on concepts like the ORB.

[DeanCIDLib]

OK, it's been updated.

[corysama]

Tremendous improvement!

Thank you for sharing your hard work with the world.