Collect documentation into github wiki

IMHO it would be good, to activate the wiki on github and collect user documentation there.

Things to move, at least:

So everyone on githib can contribute to documentation.


What problem does this solve that is not solved by the current documentation category? I personally feel the articles are more likely to be read here than on github.


For me it seems that documentation doesn’t really exists, if it only in a forum.

Yes, the wiki can be ends in a chaos. But the goal is, that everyone can contribute. Here in the forum, we can only comment something.

A forum is good for discussing, but not good for documentation.

I think this is a good idea (calmh, this means less work for you ;)).

Something that should go in there is the default config (with comments), and any optional config values. Right now I’m implementing a parser and config/cónfig.go isn’t all that readable imo.

I don’t agree with the distinction. Also, the current setup has the advantage that when someone is creating a new post with keywords matching existing articles, including documentation, that will show up as suggested posts.

This is not strictly true, although the threshold is a bit higher. It’s true that existing documentation posts can’t easily be edited by all users (I would need to grant the moderation bit), but on the other hand they can be commented on as opposed to in github. Also, new documentation posts can be written by normal users, after a while. This forum has user trust levels where you after a certain amount of participation reach “regular user” and automatically gain the right to create new documentation articles. Basically, if you’ve hung around for a while, you get trusted to generate such content.

Even before you reach that level, there’s nothing stopping you from writing an excellent “howto” or general post, and I’ll gladly move it to the documentation category, or promote your user as necessary if you like to create that type of content.

The threshold to getting an account is also slightly lower here as users can sign in with Facebook etc, as opposed to Github which is more oriented towards developers.

The default config is what you get on first startup. Write up what you think is the truth and I’ll edit if it isn’t. :slight_smile:

I’m not really eager to write all those descriptions.

Also, Im waaay too busy coding that parser xD

What’s about to open the wiki on github and see if it’s been used and if there are users how contribute?

btw. IMHO there should be exist a agument like “–init” for only creating the config file.

No, I prefer keeping documentation in one place rather than having multiple places where people might or might not find docs and might or might not contribute. Anyone wishing to contribute can do so just fine now by writing up an article right here.

If the documentation category isn’t unlocked for you yet (I’m using the general you here, not you specifically @jedie), it’s fine to write something up in dev and i’ll move it, or ask me to let you create documentation articles. The format is the same (markdown), and I’m convinced the exposure here is higher.

This is BTW what I wrote about this in the About the documentation category post;

I still stand by that until the system is proven beyond a doubt not to work. This is not a random “lets just smack the docs over here” kind of thing, it’s a conscious decision.

Well, I should be busy coding awesome stuff, but here’s just for you:

Awesime, definitely better than what I could have come up with!

I have a documentation request: “How syncthing work

We have but what i mean is the complete workflow of syncthing.

A more detailed list like this:

  • User adds a repro to node A and B
  • syncthing scans the repro folder
  • a .idx.gz file would be created
  • the index contains: …
  • User adds file on Note A
  • node B connects and request a sync
  • the index file would be transfer to node B
  • Node B compare the index file with own local repro
  • Node B requests all missing files from Node A via Block Protocol

(No idea if that list is true in the rough)

EDIT: Another “how to” request: Variant 1: I have MP3 files on PC A and not on PC B… Variant 2: I have MP3 files on PC A and a rsync copy on PC B (more or less in sync)… …How should i start synchthing?

1 Like

I would like to start a unofficial FAQ and used my fork. I have enabled the wiki and then i see that there exist already many pages:

So the wiki was used in the past?!?

I started a unofficial FAQ here:

EDIT: btw. my english is very bad. Please, correct any errors or rewrite it to clarify things…

You’re of course free to do that if you like. But could I convince you to publish it here instead, perhaps in a faq category?

Yes, the wiki was used in the past (I read parts of it when 0.8.2 was published).

One advantage would be: The wiki itself is a git repository. So forking, pull requests and the like would be possible.

But personally, I just did’t find the documentation at first, because I was used to using the wiki, and then it was gone :wink: .

I really like syncthing and most likely would switch to it for most of my syncing needs. However, I would like to add this as a new syncthing user - the current documentation system is hard to parse and understand. I keep getting lost into long discussions when I am trying to find some documentation. Also, not everything is documented (eg. Staggered File Versioning) and many ‘old’ discussions frequently use jargon which would not be familar to new users (eg Folder/Repository; I am still not sure if they are same thing?).

I do not know what is a good practical solution. Ideally, I would have preferred a html/pdf page as documentation which is part of the release and is downloaded with syncthing (& is accessible via web-gui). Or a man page would be good as well. But, these would probably require too much work. I actually liked a lot but too bad I did not find it earlier (I would have contributed to it whatever I could).

Please understand that I am not trying to be overly critical. I really appreciate developers’ hard work for providing a free open-source alternative to other (creepy) proprietary options. I understand that we have limited resource and not everything can be achieved. But I really feel that the documentation is the roughest part of using syncthing and may scare away a not-very-motivated user.

If we did have the documentation in the GitHub Wiki (for example), a tool could probably be written to scrape it and “compile” to a PDF that we could include in the release. Maybe such a thing already exists…

Documentation is now (back) on Github. Hopefully this will be an improvement and make it more accessible. It’s freely editable, so don’t be afraid to add and fix stuff!