user documentation

[jelmer]

Add some simple documentation about setup, etc.

[jelmer]

This is partially addressed, installation instructions are now present in the README.

[chmac]

Is there a list of the arguments somewhere? I guess they're maybe available via --help? As with #144 I'd be happy to spend some time adding more info to the readme, etc if I can find a list of them.

[jelmer]

Yes, --help and the manual page.

[chmac]

@jelmer Awesome, I just spotted the manpage in the code. I'll see if I can find a tool to render that into markdown. Would be great to have it in the GitHub as a markdown file so it's easily accessible, then we could link to it from the readme. What do you think?

As a docker user, the man page is a bit inaccessible to me as I need to login to a remote machine, remember the docker commands to get a terminal inside the container, etc.

I assume that --help is pretty similar to the man page, so I can just focus on that, but if that's not accurate just let me know.

[jelmer]

You can use tools like man2html to render the manpages, or find an external rendered version: http://manpages.ubuntu.com/manpages/impish/man1/xandikos.1.html

[chmac]

@jelmer Ah, that's neat, so maybe it's better to link to that page instead of the man.md file I added in #148?

[jelmer]

FWIW I think it would be great to have some user documentation for Xandikos that is written in e.g. markdown and not meant for consumption with man(1) on Linux, but e.g. rendered as HTML and published on the Xandikos homepage. Help with that would be great.

[jelmer]

Some things that we should cover in the docs:

• basics around collection detection in Xandikos and DAV basics
• how to setup Xandikos, including e.g. behind a reverse proxy
• how to use various clients with Xandikos

Advanced:

• how Xandikos stores data (e.g. syntax of the .xandikos files)
• details on supported and unsupported RFCs

[chmac]

I think the current examples folder is pretty good. Maybe the main thing is to link to it from the web site so it's easier to find.

What about folding some of the web site pages together, so the menu could be:

• Home
• About (includes clients, standards, contributing)
• Download
• Help

I'd suggest removing the news header as it seems like the news section is not up to date. Maybe make that a link to the github releases section?

Overall, my main point of feedback would be that I've found you to be incredibly helpful and responsive to queries. All open source projects are definitely not like that! That's arguably more important than documentation I'd say.

My sense is that the documentation is mostly all there, but it could maybe be easier to navigate.

What about adding a table of contents that links to every resource there is on the homepage?

• GitHub issues
• Examples folder
• Clients page
• Standards info
• Mailing list
• IRC
• Man page
• GitHub readme
• GitHub releases

I probably missed some. That could be a very low effort way to make everything more findable.

[jelmer]

That overall looks reasonable to me:

Happy linking to the GitHub issues - though we should make clear that those are for bugs/feature requests only, and not for help requests.

For now, I'm happy shipping the manpage on the homepage, but it's really not the most convenient format for documentation to be consumed on the web. Ideally we'd have a proper manual.

What do you mean with examples folder?

The README in the Git repository doesn't contain any information that's not included on the homepage today AFAICT. If it does, we should probably just update the homepage.

I don't actively maintain the GitHub releases tab, but unfortunately there is no way to turn it off. The releases list is meant to be automated but the automation must have broken. I should either fix that or we can just link to the pypi releases.

[chmac]

I guess using GitHub discussions instead of the mailing list would be more accessible to GitHub users, but maybe less accessible to others. Although I would say that overall, having a "I can ask a question, and read other questions & answers" place is probably more useful to more users than a "sign up and receive every message everyone sends about this package" place.

[jelmer]

That's a good point - I've enabled discussions.

I've also added some documentation under docs/ that will shortly also be available on https://www.xandikos.org/docs/

I'm interested in hearing what else should be covered in the documentation and whether it is understable at the moment.

[chmac]

@jelmer Docs look great.

What about adding a "Running from docker-compose" section with an example compose file?

I couldn't find a link from the docs back to the main homepage. Or was your idea to replace the homepage with the new docs site? I find the structure of the docs site much easier to navigate with main topics, then sub headings, starting with a full list of the content. If the content from the site (features, limitations, etc) were copied over, I think the docs could make a great replacement for the homepage.

[jelmer]

I'll happily take patches to document the useof docker-compose, but am not in a position to do so since I don't use it myself.

My plan is to add a link from the homepage. The docs won't include e.g. the download links.

[chmac]

There's a docker compose file in the examples folder from one of my PRs. I think linking to or including that would be sufficient to show folks how to get started.

[jelmer]

There's already a one-sentence reference to that file in the docs.

[alensiljak]

Some feedback from a newcomer. I see two entry points for the project: the homepage and the GitHub repository (readme). None of these links to the docs, wiki, stack exchange, or other forms of documentation.

Wiki and stack exchange have a very low barrier to entry for the newcomers, both to find or ask the questions, or provide answers and articles.

[chmac]

@jelmer What about including the compose file in the docs in the same way as the kubernetes file?

I think folding all the website content into the docs would make the whole thing much easier to navigate. Then the readme could be simplified and just link to the docs. At least, that's definitely a pattern I'm familiar with from many other packages I've used.

[stappersg]

(Timezone point of view is UTC+1) This morning:

What about including the compose file in the docs in the same way as the kubernetes file?

Last night:

I'll happily take patches to document the useof docker-compose

[jelmer]

Some feedback from a newcomer. I see two entry points for the project: the homepage and the GitHub repository (readme). None of these links to the docs, wiki, stack exchange, or other forms of documentation.

That's a good point - I've just added a link to the documentation from the website and the README.

There is no official stackoverflow or wiki for Xandikos; for help, the official channels are either the IRC channel, mailing list or GitHub discussions. I think that's already plenty of options, and don't really want to recommend other options that nobody is guaranteed to be answering questions on.

That shouldn't stop anybody who wants to ask questions about xandikos on stackoverflow.