Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Restructuring the documentation #537

Open
contrapunctus-1 opened this issue Jul 24, 2020 · 15 comments
Open

Restructuring the documentation #537

contrapunctus-1 opened this issue Jul 24, 2020 · 15 comments

Comments

@contrapunctus-1
Copy link

I wanted to add an FAQ on how to copy an existing Syncthing configuration to a new system (and removing keys.pem on the new one). 😅 But in course of that I noticed something about the Syncthing documentation.

I really like this idea for structuring documentation. It involves organizing documentation into four categories - tutorial, how-to guides, reference, and explanation.

My personal understanding of it is -

  1. tutorials are for beginners, teaching them about basic usage, solely in terms of actions (with no 'explanations' of underlying concepts), and trying to make it fun.
  2. how-to guides are for achieving specific goals, with some scope for variation. Meant for users who have gotten past the tutorials, and are trying to meet specific usage/configuration needs.
  3. the explanation is for describing the design of the software at a high level, and how it came to be - how various components of the project fit together. Meant to guide beginner contributors in exploring the source, and power users trying to gain a deeper understanding of the software.
  4. the reference documentation is for describing the software in detail - functions, variables, classes, methods, and their correct use (with no awareness of 'use for a particular purpose'; that's for the how-to guides). Meant for experienced contributors looking up a definition or its usage, or trying to get an overview of the API, without dealing with the implementation (source code) or how it fits together (explanation).

In comparison, in Syncthing's current documentation, those concerns are mixed up rather haphazardly, I'm sorry to say.

I'd like to try to restructure Syncthing's documentation in this manner, because I believe it would be greatly improved by it.

What does the community say?
@AudriusButkevicius
Copy link
Member

I think that's fine as long as we don't lose existing content along the way, however I'd sketch out a rough skeleton of what goes where before doing all the work, just in case someone disagrees, so that you don't do all the work for it to be refused.

@calmh
Copy link
Member

calmh commented Jul 24, 2020

What Audrius says. I agree with the haphazardness and that should be done. An early sketch is better than a lot of work up front. We will need a set of redirects as well probably, for maintaining external links.

@contrapunctus-1
Copy link
Author

contrapunctus-1 commented Jul 24, 2020 •
edited
Loading

Thank you for your encouraging response. 😁 I'll definitely try to avoid losing any existing work.

I like the idea of a rough sketch - here goes 🙂

The tutorial

The "Getting Started Guide" looks like a good starting point for making a tutorial. I can see a lot of explanation there, which I'd try to move so it becomes leaner.

The existing FAQ

Coming to the FAQ... (significantly different renames are indicated with -> <newname>)

How-to

The following seem suited to a how-to section.

  1. "Why is the sync so slow?" -> How to diagnose slow sync speeds
  2. "How do I serve a folder from a read only filesystem?"
  3. "I really hate the .stfolder directory, can I remove it?" -> How to sync without a .stfolder directory (?) (probably redirecting/linking to the previous one, as now)
  4. "How do I rename/move a synced folder?"; some of the text can be moved to a Explanation/"Moving folders" topic
  5. "How do I configure multiple users on a single machine?"; I would like to expand this, adding steps and configuration options specific to this goal.
  6. "How do I access the web GUI from another computer?"
  7. "How can I exclude files with brackets ([]) in the name?"
  8. "I don’t like the GUI or the theme. Can it be changed?" -> "How to change the theme", and either Explanation or README - "Other frontends"
  9. "Where do Syncthing logs go to?" -> "How to access the logs"
  10. "How can I view the history of changes?"
  11. "How do I upgrade Syncthing?"
  12. "Where do I find the latest release?"
  13. "How do I run Syncthing as a daemon process on Linux?"
  14. "How do I increase the inotify limit to get my filesystem watcher to work?" -> "How to address inotify limit errors on Linux"
  15. "How do I reset the GUI password?"
  16. And lastly, the one I need to add - "How to clone a Syncthing configuration on another machine" :D

Explanation

The following seem suited to an Explanation section

  1. "What things are synced?" (-> "What is synced")
  2. "What if there is a conflict?" (-> "How Syncthing handles conflicts")
  3. "Should I keep my device IDs secret?" (-> "Device IDs"; some text from the Getting Started Guide can also be moved here)
  4. "When I do have two distinct Syncthing-managed folders on two hosts, how does Syncthing handle moving files between them?" - probably as part of a larger section describing sync behavior in various scenarios - I seem to have read quite a few thematically linked entries in the FAQ. I'm not sure what scenario this one is describing, though 🤔
  5. "Does the audit log contain every change?"

Uncertain

  1. "Why does it use so much CPU?"; could be split into a "How to limit resource usage" and a Explanation/"Understanding resource usage" topic
  2. "Am I able to nest shared folders in Syncthing?"; could be a Explanation/"Nested folders" topic
  3. "Why do I see Syncthing twice in task manager?"

For prospective users

The following seems to be information a prospective user may want to know. I'm not sure where to put it - the README, the documentation front page, or even just the FAQ, same as now. Wherever a prospective user is most likely to see. FWIW I think of these more as "marketing" than strictly "documentation".

  1. "What is Syncthing?"
  2. "Does Syncthing support syncing between folders on the same system?"
  3. "Is Syncthing my ideal backup application?"
  4. "Why is there no iOS client?"
  5. "Why is the setup more complicated than BitTorrent/Resilio Sync?"

Whew! 😪 This is huge, and we've barely begun. I see a lot of stuff in Usage, much of which gets split into how-to/explanation, and then there is the Development section. Massive effort 😄

Let me know what y'all think! 🙂

EDIT - if the How-to or the Explanation gets longer than a certain point, we can, of course, create subsections for them. I have a feeling it's going to be necessary.

@imsodin
Copy link
Member

imsodin commented Jul 24, 2020 •
edited
Loading

What's the scope of what you'd like to tackle - reorganisation the docs structure or "just" (it's a lot on its own) structuring the FAQs? From what you wrote in general I got the impressions it's the docs in general, however your latest comment is very low-level (as in "in-detail"), looking at individual FAQs entries. What I imagine as a first step to discuss/agree on, is a very rough outline of the structure and where current content (again only very roughly, keywords coming to mind: config, api, releases). Could be some kind of semi-imaginary table of contents or something.

@contrapunctus-1
Copy link
Author

contrapunctus-1 commented Jul 24, 2020 •
edited
Loading

@imsodin It's restructuring the entire documentation into certain groups, each of which serves a specific function and does not try to do something covered by another group. The best outline I can give is in the issue - in other words -

docs.syncthing.net
* basic usage tutorial
* how-to guides
* explanation
* reference
[* FAQ]

It would be repetitive to mention the topics ("config, api, releases") covered in each, because they will be covered in more than one group. For example, if we consider the subject of configuration -

  • configuration options will be exhaustively listed in Reference/Configuration, with no information of usage or design or history; at most with valid values and important caveats;
  • important/interesting configuration options will be described and commented on in Explanation/Configuration, maybe with some background about them;
  • and some configuration options can be mentioned (as far as they help in achieving a certain goal) in one or more How-To Guides.

A fifth group is emerging which is aimed at prospective users, which, as I've said, I consider to be more suited for 'marketing'. I don't know if we want that in the documentation or elsewhere.

I mark the FAQ in square brackets, because while I'll try my best to move everything out of that and remove it as a "branch" of our tree, it may be the case that some things really are better off put in that.

I hope that makes it clearer.

@imsodin
Copy link
Member

imsodin commented Jul 24, 2020 •
edited
Loading

Partly :)
What I am looking for is some middle ground between the super high-level part in the first post (separate docs by those principles) and taking existing content apart and assigning it to those principles (as I understand it that's what you started to do for FAQs in #537 (comment)). The former is nice, but also very vague, and the latter is already a whole lot of work. That's why I mentioned a table of contents and specific keywords. Of course config will be mentioned all over, there's probably still going to be one place where it is (supposed to be) complete, as you wrote most likely in the reference. What about e.g. contribution guidelines or release process? Probably a howto, however not relevant to users. So maybe you'd split the howto into a usage and a development section? These are the kind of "mid-level" questions I believe make sense to lay out and agree on before diving deep and investing lots of time into making the actual content work with the new structure (because I believe that's going to be a lot of work, that ideally would be shared - maybe some more contributors could be motivated (me included, maybe :) )).

And some parts of the FAQ are somewhat special, because they explicitly exist to make support easier. As in if you get the same question the umpteenth time, you can just link to the matching question (hoping that eventually enough links are lying around that even the laziest search leads to them - one can dream). Some form of that will probably have to persist, but I agree that a lot of it can be moved to better places.

And the marketing material can maybe go to the "docs landing page" and some you mentioned can stay in faq ("why no ios" is a prime example).

@contrapunctus-1
Copy link
Author

Yeah, it may help us to make development- and usage-related subsections -

docs.syncthing.net
* Basic usage tutorial
* How-to guides
  + Users
     - How do I configure X?
     - How do I set up Y?
     - ...
  + Developers
     - How do I set up a development environment?
     - How do I get started making a frontend for Syncthing?
     - ...
* Explanation
  + General (likely to be of interest to both power users and developers)
  + Developers (likely to only be of interests to developers)
* Reference
[* FAQ]

How-tos are goal-oriented (think of them in the form "How do I ...?"), so "Contribution Guidelines" probably don't fit that, although a "How do I contribute to Syncthing?" guide might link to Reference/Contribution Guidelines or Explanation/Contribution Guidelines (depending on how it's written; the former would be a strictly informative listing of these guidelines, the latter could take the time to explain the whys and wherefores of it.) It's the same for the "Release Process".

I can try to make what I think you're asking for, but it's more work and will take a day or two. I'll need to skim through the entire documentation, and come up with a more detailed outline.

It is indeed a major undertaking, and I'd be grateful for help.

@imsodin
Copy link
Member

imsodin commented Jul 24, 2020

Right, that's already quite a bit of work in and of itself, however that's at least what I understood Audrius' "skeleton" and Jakobs "sketch" to be respectively what I'd consider useful to have like an early "top-level" review to prevent investing lots of time up-front for things that might have to be changed later. Anyway, thanks already for your interest and starting to think/work on it!

@contrapunctus-1
Copy link
Author

contrapunctus-1 commented Jul 25, 2020 •
edited
Loading

#537

Okay, here we are. This is pretty quick and dirty, as I was trying to work quickly and not be too thorough. I know it's not exactly the "middle ground" @imsodin asked for - rather a continuation of my "detailed" FAQ restructure outline - but I couldn't think of a better way to illustrate the proposed outcome. 😅

The heading structure ahead represents the website/documentation structure.

I envision pages linking to their related entries in other sections, almost all the time. e.g. the tutorial, at the end, linking to the how-to guides.

Sketch 2

Tutorial (<- Getting Started - but made leaner)

How-to guides

For users

Installation and upgrade

Running

Troubleshooting

The Web GUI

Advanced users

For contributors

Explanation

For contributors

Reference

For prospective users

Rather than in the documentation, let's try to address these at the potential point(s) of first contact.

  1. What is Syncthing?
  2. Does Syncthing support syncing between folders on the same system?
  3. Is Syncthing my ideal backup application?
  4. Why is there no iOS client?
  5. Why is the setup more complicated than BitTorrent/Resilio Sync?

Comments

Ah, the Reference. The idea is to make it "code-oriented" -

  1. make sections for each source file
  2. insert every function signature, variable, including docstrings, from the file
  3. repeat

This can all be generated and updated programmatically, of course.

Optionally - move whatever I've put in Reference right now to Explanation.

Not sure where to put

@calmh
Copy link
Member

calmh commented Jul 26, 2020

Looks very promising!

@contrapunctus-1
Copy link
Author

contrapunctus-1 commented Jul 26, 2020 •
edited
Loading

@calmh I'm glad you like it! 😃

@AudriusButkevicius , @imsodin , others - what do you say?

@imsodin
Copy link
Member

imsodin commented Jul 26, 2020

Agree, looking good already :)

I have some comments on individual entries, but I believe that would be easier to discuss on a WIP PR of a branch that has a skeleton of the new structure (mostly to have different threads for different topics). Things like that I'd expect the rest api in the reference section (plus a howto). And I kinda liked the process used for a big PR recently where there's a main PR branch and then one can do smaller PRs against that one branch - prevents those monster-PRs that can grind the browser to a halt :P And can also facilitate collaboration, e.g. when you are the main driver of this restructuring and at a later stage someone starts contributing too.

I like how you approach the process and the content. If you are aware that this is a lot of work and feel like you have the motivation and time to tackle a sizeable chunk of that, from my side I am very happy if this goes ahead and into a concrete phase.

@contrapunctus-1
Copy link
Author

@imsodin I'm glad you like it 😀 It seemed more daunting when I started and less so now that I've gone through the entire documentation, although I guess the redirects will be some additional work. At any rate, I do see myself as being able to carry it out.

And I kinda liked the process used for a big PR recently where there's a main PR branch and then one can do smaller PRs against that one branch - prevents those monster-PRs that can grind the browser to a halt :P And can also facilitate collaboration, e.g. when you are the main driver of this restructuring and at a later stage someone starts contributing too.

Sounds good; please let me know how to make this workflow happen, as all my FOSS PRs so far have been very simple ones.

@imsodin
Copy link
Member

imsodin commented Jul 28, 2020

I thought I responded yesterday already, but apparently didn't send - sorry about that:
The multi-PR thing might not be necessary/useful in the end. Nevertheless the only thing required is that the main work is on a branch in this repo. I just added you as a contributor, you should be able to push to a new branch on this repo.

@contrapunctus-1
Copy link
Author

Sorry for the break. I've started working on it, piece by piece. Thought of starting by moving things from the FAQ to a How-to section, for which I have created a restructure-faq branch. Moved two entries today.

I've never used ReST or Sphinx before, so apologies if I get something wrong.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@calmh @AudriusButkevicius @contrapunctus-1 @imsodin