Veilid documentation suggestions

Documentation is being written for you whenever a developer answers a question or there's a discussion on gitlab. Digging through these discussions is unnecessary friction for new developers.

You need an inbox to collect information to add to the developer book. In the short-term, this could be your own text file or other system. But I highly recommend building a collaborative staging ground that has very little friction. For example:

This discussion contains crucial information that should be added asap to the developer book: DHT records are encrypted by default now, and you can share the encryption_key field with peers to give them access.

I know you said you are planning to add that info, but my suggestion is you enable a doc tag or something on gitlab and ask developers to use it whenever their discussion contains new information that should go in the book. Once you've added the info, you remove the tag.

Same with discord: have people forward messages/threads to a specific channel.

Finally, create a low-friction way for people (veilid-core devs or app developers or discord users) to add to the "staging ground". My suggestion is use a gitlab wiki.

Then we have some feeds of information that can be added to the book, much of it already pre-written.

Then add a page to the developer book explaining how to use these channels.

Define and refocus around your audience. The audience needs to be crystal clear to you when you're writing. This is true for the website and the book.

To me, it seems like app developers are the most important audience. For both the website and the developer book. There are no end users, since there are no stable apps, and when those users materialize, their apps should have their own documentation. And I personally would not focus too on attracting veilid-core developers either - that will happen naturally if you get more app developers. But right now, there is a working core and what the project needs is for people to start building stuff with it. That in itself will generate traffic to the project, plus provide valuable steering information, and some of those app developers will likely contribute to veilid-core.

You don't need to make a detailed hypothesis about what the audience knows and doesn't know. It's more that you always have a clear audience definition. And you know what they need to know.

If it helps, you can literally write who the audience is at the top of documents.

If you refocus on the audience, other changes might naturally flow from that. For instance, I saw there was some discussion on Discord about referencing the Kademlia lineage of Veilid's DHT in the developer book.

Actually, I think you should remove references to the search algorithm, the XOR distance formula, etc. First of all, it is extremely hard to grasp what that means just by reading that text. It's just a complex topic. If you look at the original kademlia paper it's full of images to make it more accessible. And there are going to be better explanations you can link to elsewhere.

Sounds crazy, but really app developers do not need to know how Veilid's DHT works!

What they need to know are its properties (security, privacy, availability, timeout, schema, limitations) and the intended use-cases. These are not well explained right now.

I would say something like:

Veilid's DHT is like a secure distributed cache you can use for <…what?>. The original design is similar to Kademlia (< wikipedia link, paper link, Youtube link…>), but Veilid's DHT has security and privacy improvements. If you want to read a detailed explanation of Veilid's DHT, visit <link to veilid internals dht chapter>. The most important things you need to know about the DHT are:

• You can use it for …..
• privacy/security property X
• privacy/security property Y

<Insert rest of the existing explanation about DHT records and schema>

This is just one example.

The above suggestions will help with the content of the developer book.

To generate more positive interaction and uptake, you need to think about the "shape" of information, including outside the developer book. This is about where you put info.

Thinking in terms of the audience is helpful here too. You don't want people to have to click around to find basic stuff. You don't want to have information duplicated too many places, or split up randomly.

Ideally you should create intentional flows for each audience, with as few hops as possible in each flow.

Which leads me to…

The website drives me crazy.

At the very least, the homepage at veilid.com should link directly to the gitlab, the developer book, and the discord.

In general, the website appears reasonable at first glance, but it's actually confusing and overcomplicated.

Look at the yggdrasil homepage:

Now look back at the Veilid homepage.

Do you see what I mean?

Let's check out the first subpage, How It Works:

This page is bad. Why is it split up into more subpages? Why doesn't it "flow" into the Veilid internals book?

Now the Why Veilid page:

This is the content that should go on the homepage!

Now notice how the Contribute page fails to link to the Git repository:

Here's another weird one, it's a hidden page called Getting Started:

There's no need for a subpage here, especially one that's not directly accessible from the homepage. But really, what about putting this info in the developer book instead?

Also the Accessibility page, who is it for? Who is the audience? Why is it a top-level page?

I could keep going:

• the links at the bottom, under "More Information", "Veilid on Social Media", and "Contact Us" - This is not useful information for 99% of visitors. Link the developer book and the discord, at least.
• https://veilid.com/faq/ should be more prominent, and more complete.