Needs proper user documentation

[aspiers]

As seen with questions like #223, these source services are complex enough that we need proper docs for users, not just a README and some .service XML files.

• [ ] decide location of docs
• [ ] decide format of docs
• [ ] broken link to obscpio delta store in README (Issue #193)
• [ ] add example of extract parameter

See also the OBS Documentation Trello board, and all issues with the "documentation" label.

[aspiers]

@adrianschroeter @M0ses @tomschr Any thoughts on where this should live and what format it should have? My personal preference is that it should be in this repo so that changes to the code and docs are always made atomically in the same commit.

[tomschr]

@aspiers Thanks Adam for bringing this up!

Any thoughts on where this should live

It depends, if you want to have it inside an official (open)SUSE documentation or not. I guess, it's not bound to a product, so it can live on its own. In that case, you could publish your documentation as GitHub pages somewhere under http://opensuse.github.io/obs-service-tar_scm/.

Travis could do an automatic push to the gh_pages branch once you consider your commit(s) as release ready. :wink: We do mostly the same with our documentation on our beta side at http://susedoc.github.io/ (kind of "public docserv").

That will give you all the benefits you like to have: code and docs are in the same repo and can be managed together.

what format it should have?

You can use whatever format you like. As the project is a Python module, Sphinx's RST would be a natural fit.

My personal preference is that it should be in this repo so that changes to the code and docs are always made atomically in the same commit.

Fully agree. :+1:

[aspiers]

@tomschr commented on 19 Jun 2018, 11:56 BST:

@aspiers Thanks Adam for bringing this up!

Any thoughts on where this should live

It depends, if you want to have it inside an official (open)SUSE documentation or not. I guess, it's not bound to a product, so it can live on its own. In that case, you could publish your documentation as GitHub pages somewhere under http://opensuse.github.io/obs-service-tar_scm/.

That sounds like a good idea.

Travis could do an automatic push to the gh_pages branch once you consider your commit(s) as release ready. :wink:

You mean using GitHub Pages Deployment? Nice idea!

We do mostly the same with our documentation on our beta side at http://susedoc.github.io/ (kind of "public docserv").

That will give you all the benefits you like to have: code and docs are in the same repo and can be managed together.

Yup.

what format it should have?

You can use whatever format you like. As the project is a Python module, Sphinx's RST would be a natural fit.

Makes sense.

My personal preference is that it should be in this repo so that changes to the code and docs are always made atomically in the same commit.

Fully agree. :+1:

OK, sounds like we have a plan! Now we just need someone with free time :stuck_out_tongue_winking_eye:

[tomschr]

Travis could do an automatic push to the gh_pages branch once you consider your commit(s) as release ready. wink

You mean using GitHub Pages Deployment? Nice idea!

Yes, exactly.

[TheRealBro]

Bump, this would be helpful!

[dannysauer]

So... :D

[StayPirate]

+1

[pwitcher]

Hello, I'm a tech writer with some free time. May I contribute to this docs issue? If so, can we have an informal TOI?

[dcermak]

Hello, I'm a tech writer with some free time. May I contribute to this docs issue? If so, can we have an informal TOI?

@pwitcher It would be great to have a better documentation of this OBS Service. What kind of help would you need?

[pwitcher]

@dcermak I would need an overview of the service and how it works, and who the audience is. Can you point me to any design docs or other descriptive documentation?

[dcermak]

@M0ses could you help out @pwitcher here? You appear to be one of the most frequent contributors this service.

[M0ses]

@pwitcher : THX for volunteering. I started a gist to share information without blowing up this issue too much:

https://gist.github.com/M0ses/0a507a34e80f46ffa2d0c9240925516b

[dannysauer]

/comes back 4 years later... Sigh. 🤣

[aspiers]

For avoidance of doubt, unfortunately I won't be able to help with this any more. I haven't been involved with tar_scm since 2018.