~qaul/community

4 2

Re: Documentation feedback: technical intro

Details
Message ID
<180ed7a7-7d8d-40c4-b6ca-6715b9aca480@www.fastmail.com>
DKIM signature
pass
Download raw message
I really like it. I think publishing this as-is immediately will be beneficial for technical intro. 

I just have a minor question: 

I am assuming that the sections like "libqaul internals" section will be its own sub-page? I currently do not understand (or lack of project understanding) whetber "libqual internals" is a "Layer" subheading, as in, is it truly a part of the Layer? 

I think "apps" and "service api" do seem like layers within qaul.net.



On Mon, Jan 13, 2020, at 11:58 AM, Katharina Fey wrote:
> Hey,
> 
> I rewrote the technical documentation intro to be more up-to-date and
> understandable.  I'd really appreciate some feedback on how it reads, if
> there's any explanations missing or if some parts are badly structured.
> Thanks!
> 
> ~ spacekookie
> 
> ---
> # Technical Documentation
> 
> Welcome to the qaul.net technical documentation!
> 
> This section is aimed at two different types of people:
> 
> 1. People wanting to contribute to qaul.net and it's libraries
> 2. People wanting to write their own apps for a qaul network
> 
> This page will offer a short introduction to the project structure to
> get you started.  On each section in this document there are pages and
> chapters that go into more detail than is required here.
> 
> 
> ## Introduction
> 
> Fundamentally, qaul.net is a highly distributed system.  As such, it
> is not accountable to a single set of rules across all devices that
> are part of this system.  It is important to make the distinction
> between "qaul.net", the application, "qaul network", the distributed
> network of devices, and other components provided by the project that
> can be used to write decentralised applications.
> 
> The primary component in this ecosystem is called libqaul.  It
> provides an abstraction layer for a distributed network of devices,
> the users that interact with each other and the messages and data that
> can be exchanged.  The API of this library is called the "service API"
> in other parts of the docs.
> 
> Built on top of it are services (or apps), that provide more specific
> functionality, such as text messaging or file sharing.  qaul.net (the
> app) is merely a GUI and collection of a few different services all
> running on the same libqaul instance on one device.
> 
> 
> ## Layers
> 
> The following sections will outline the different layers present in
> qaul.net (the application), then there are pages for more details on
> how to interact with each of these layers.
> 
> 
> ### libqaul: services & apps
> 
> As mentioned in the introduction it is possible to build applications
> (or "services") with libqaul, that can interact with each other on a
> distributed network.  These services provide high level functionality
> such as sending text messages, a collaborative public feed (similar to
> mastodon), and voice calls.
> 
> Following is a list of all the services that come bundled in qaul.net
> by default (with links to sub pages for details).
> 
> - [feed]()
> - [messages]()
> - [files]()
> - [voices]()
> - [radio]()
> 
> The reason why qaul.net is built in such a modular way is to allow you
> to write your own services, with their own functionality and UI, that
> gets to interact with an existing service and user ecosystem.  libqaul
> also helps you to build your application in a way where it doesn't
> rely on central servers on a network and keeping your users' data
> safe.
> 
> 
> ### libqaul: service API
> 
> The interface to libqaul is called the service API, and a versatile
> abstraction over a decentralised network.  It handles local user
> authentication, network user discovery, binary payload messages,
> contact data, and even encrypted file storage at rest.
> 
> The API itself is available as an async Rust library and ffi C
> interface, with some optional IPC add-ons:
> 
> - [http/json:api]() - this is how the qaul.net GUI is hooked up
> - [socket-ipc]() - using a capt'n proto ipc protocol over unix sockets
> - [android-ipc]() - implementing an Android specific ipc interface
> 
> The idea behind the variety of IPC interfaces is that your application
> can bundle it's own copy of libqaul, to provide the network backends
> required to join a mesh network, however it can also connect with a
> running instance if one is available.  This way resources can be
> shared.
> 
> 
> ### libqaul: internals
> 
> The internals of libqaul are intirely written in Rust, and hook into
> various storage and networking abstractions.  libqaul primarily uses
> two libraries, also written as part of this project, to do it's job:
> alexandria, and ratman.
> 
> 
> Attachments:
> * signature.asc

Re: Documentation feedback: technical intro

Details
Message ID
<87wo9v11zm.fsf@kookie.space>
In-Reply-To
<180ed7a7-7d8d-40c4-b6ca-6715b9aca480@www.fastmail.com> (view parent)
DKIM signature
missing
Download raw message
Hey!

> I really like it. I think publishing this as-is immediately will be
> beneficial for technical intro.

Cool, that's good to hear.  Never sure being in the weeds of things if
my explanations are going to be helpful ;)

> I just have a minor question: 
>
> I am assuming that the sections like "libqaul internals" section will
> be its own sub-page? I currently do not understand (or lack of project
> understanding) whetber "libqual internals" is a "Layer" subheading, as
> in, is it truly a part of the Layer?

That is a fair question. Technically 'libqaul' is a layer in the stack,
but you're right that this could be confusing.  Would you not have the
'libqaul internals' section under 'layers', or do you think renaming it
to just 'libqaul' might be better?


~ spacekookie

Re: Documentation feedback: technical intro

Details
Message ID
<66482fe0-4196-4697-be57-20f5ac139cc1@www.fastmail.com>
In-Reply-To
<87wo9v11zm.fsf@kookie.space> (view parent)
DKIM signature
pass
Download raw message
> Never sure being in the weeds of things

You are all experts and you should want noobs like me. :)

> 'libqaul' is a layer in the stack

I agree. This entire section is only about libqaul so makes sense
to not talk about other layers in the entire stack.

> Would you not have the 'libqaul internals' section under 'layers',
> or do you think renaming it to just 'libqaul' might be better?

If you are asking about the title "Layers" then I do think the
section can be renamed to libqaul with the three subsections
as they are (minus "libqaul:" in front since it is redundant?).


On Mon, Jan 13, 2020, at 4:27 PM, Katharina Fey wrote:
> Hey!
> 
> > I really like it. I think publishing this as-is immediately will be
> > beneficial for technical intro.
> 
> Cool, that's good to hear.  Never sure being in the weeds of things if
> my explanations are going to be helpful ;)
> 
> > I just have a minor question: 
> >
> > I am assuming that the sections like "libqaul internals" section will
> > be its own sub-page? I currently do not understand (or lack of project
> > understanding) whetber "libqual internals" is a "Layer" subheading, as
> > in, is it truly a part of the Layer?
> 
> That is a fair question. Technically 'libqaul' is a layer in the stack,
> but you're right that this could be confusing.  Would you not have the
> 'libqaul internals' section under 'layers', or do you think renaming it
> to just 'libqaul' might be better?
> 
> 
> ~ spacekookie
> 
> Attachments:
> * signature.asc

Re: Documentation feedback: technical intro

Details
Message ID
<87o8v70zdg.fsf@kookie.space>
In-Reply-To
<66482fe0-4196-4697-be57-20f5ac139cc1@www.fastmail.com> (view parent)
DKIM signature
missing
Download raw message
> I agree. This entire section is only about libqaul so makes sense
> to not talk about other layers in the entire stack.
>
> [...]
>
> If you are asking about the title "Layers" then I do think the
> section can be renamed to libqaul with the three subsections
> as they are (minus "libqaul:" in front since it is redundant?).


Oooh, yes okay now I understand what you mean :) Yes, that's a good
idea.

Actually thinking about it, there should be a later section about Ratman
too, so maybe splitting it:

## Layers

### Services & Apps

### libqaul
#### Service API
#### Internals

### Ratman
... ?

What do you think? Alternatively we drop the "layers" and bump all the
headings down by one.

Re: Documentation feedback: technical intro

Details
Message ID
<3beb5444-c347-44d9-8792-23aa095ae8f9@www.fastmail.com>
In-Reply-To
<87o8v70zdg.fsf@kookie.space> (view parent)
DKIM signature
pass
Download raw message
> What do you think? Alternatively we drop the "layers" and bump all the
> headings down by one.

I like this with Layers heading except are these truly layers, 
as in do they  live atop one another? Otherwise we could
use "Components"? I am not aware of the actual details
so leave it to you for Layers vs Components etc. but I like it
given RATMAN is also gonna be there. :)


On Mon, Jan 13, 2020, at 5:23 PM, Katharina Fey wrote:
> > I agree. This entire section is only about libqaul so makes sense
> > to not talk about other layers in the entire stack.
> >
> > [...]
> >
> > If you are asking about the title "Layers" then I do think the
> > section can be renamed to libqaul with the three subsections
> > as they are (minus "libqaul:" in front since it is redundant?).
> 
> 
> Oooh, yes okay now I understand what you mean :) Yes, that's a good
> idea.
> 
> Actually thinking about it, there should be a later section about Ratman
> too, so maybe splitting it:
> 
> ## Layers
> 
> ### Services & Apps
> 
> ### libqaul
> #### Service API
> #### Internals
> 
> ### Ratman
> ... ?
> 
> What do you think? Alternatively we drop the "layers" and bump all the
> headings down by one.
> 
> Attachments:
> * signature.asc