Improving Documentation

[pimotte]

There are holes in the documentation in various places. For those involved longer with the project it is not always clear where documentation is clearly lacking and where improving it is not a priority.

This issue serves as a central place to mention and discuss lacking documentation.

[binwiederhier]

I believe there needs to be a User Guide and a Developer Guide a la:

User Guide:

• Installation
• General Overview
  • (topology, client-only, ..)
  • (differences to X, Y an Z)
• Basic Usage
  • CLI mode (init/up/down/status)
  • Daemon/server mode
• Commands
  • (command man pages)
• Plugins
  • Plugin Concept
  • Managing Plugins (install/remove/list)
• Configuration Files
  • Per-folder configuration (.syncany, config.xml, .syignore)
  • User daemon configuration (daemon.xml)
  • Global user configuration (userconfig.xml)

The developer guide should be structured similarly.

Now framework-wise: We could either just do

1. a simple single-page markdown file
2. multiple markdown files linking to each other
3. use something like readthedocs.org (example)to automagically create the documentation

I'm fine with either 1 or 3. Personally I don't like multi-page documentations, because it basically disables Ctrl+F.

Thoughts?

[pimotte]

I'm also fine with anything that is reasonable to maintain and full-text-searchable. readthedocs seems quite extenisive, and at some point I would have said it's overkill, but given how great travis and gradle have been, I can get on board with stuff that is a little work to set up and runs itself thereafter.

I'm not sure if this document needs a compare-and-contrast, but otherwise the contents LGTM. I imagine this document would turn into more of an Admin Guide when we stabilize?

[binwiederhier]

Decided to to option (3).

• Started at this repository: https://github.com/syncany/syncany-docs
• Built to http://syncany-user-guide.readthedocs.org/

[binwiederhier]

In case anybody is wondering why it's so quiet: I'm mainly working on the Syncany User Guide right now. Check out http://syncany-user-guide.readthedocs.org/. It's slowly growing :-D

[binwiederhier]

• What is Syncany? (100%)
• Installation (100%)
• Gettings Started (100%)
• Concepts (100%)
• Commands (100%)
• Plugins (100%)
• Security (100%)
• Configuration (100%)
• Appendix: Man pages (100%)

If anyone is interested, the Installation page is ready for review. Comment here or fork+pullrequest.

[binwiederhier]

Looking really good.

• What-is page is done. With nice graphics and use cases.
• Installation is also done
• I like the Getting Started page best so far.

@pimotte @guitarlum
I drew a nice little diagram for [use case 2] on the what-is page. As of today, this is not possible, but I'd like to discuss how we could realize that. Any comments? IRC is probably best for that.

Also: Should we leave the use case there if it's not possible yet?

[binwiederhier]

@cr0
Since you wrote the Samba plugin, maybe you can help with the plugin security section in the documentation. Do you have any idea if the your plugin implementation uses any kind of transport encryption. I don't know enough about SMB/CIFS or the jCIFS library to answer that question and googling didn't really help.

[pimotte]

What exactly in usecase 2 is not possible today? I just see a dedicated server with 3 repositories. The webinterface is in demo, but it won't be long before that's actually useable.

[cr0]

Smb does support transport encryption but only for version 3 which is supported by Windows Server 2012 and Windows 8.
After doing a little research I found out that jCIFS only supports NT LM 0.12 which is SMBv1. Long story short: I don't think that jCIFS supports transport encryption.

Perhaps you simply start up wireshark and have a look (I would do it by myself but wireshark's a mess on OSX).

[binwiederhier]

@cr0
Thanks. I'll just document it like this (no encryption). And if I find the time I'll maybe test it with Wireshark :-)

@pimotte
The web interface part already works (given the PoC status of the simpleweb plugin). The project X and Y stuff, however, does not work at all:

• Right now we can set up the projects in a remote daemon and we can run commands remotely on that daemon. However, we cannot sync files to a local folder (Armin's PC) and have the storage connected to a remote server.
• To achieve a three layers as the diagram depicts (Syncany Client, Syncany Server, Dumb Storage), we'd have to have a "syncany-client" plugin in Armin's Syncany client, a "syncany-server" plugin in the company's daemon which uses a "s3"/"sftp" plugin inside. So Armin's client would use the syncany-client plugin to talk to the daemon; and the daemon would translate requests to the actual backend storage.

Example: armin: upload(database-123) --[syncany-client/REST]-->daemon: upload--[s3]-->s3 storage

I hope this is understandable...

[binwiederhier]

@pimotte
Ping :-D

[binwiederhier]

Also: New URL at http://syncany.readthedocs.org/en/latest/

[pimotte]

@binwiederhier
pong.

With regards to time management, I would categorize this as "important, but not urgent", so I'll take the effort to actually understand this in a week or so.

[binwiederhier]

Sure. Sorry... ;-)

[binwiederhier]

Even though things might not be perfect, I hereby consider this issue closed.