[documentation] non-PR doc editing

[stas00]

Is there a way we could have some of the docs that can be edited other than through PRs?

For example I've been working on these 2 docs:

• [wip] [doc] Parallelism notes #9766
• [wip] [doc] Performance and Scalability notes #9824

1. So I do a lot of incremental edits and doing that via PRs would be very difficult to do as it's a big work in progress - that's why I started with just an Issue comment
2. it's important that the work in progress is readable, PRs aren't great for that
3. I'd be great if others could collaborate on editing
4. Yet, as these shape up, we want these in the documentation and not a random page somewhere
5. I already run into a problem with git where somehow it switched to an old edition of the comment and won't let me revert to the newer version of the comment.

Perhaps we could have some wiki pages that can be linked into the main menu? Then many can collaborate and there is no need to do frequent PR cycles. Not sure if it's great, since it'd take the user away from the main website?

Or perhaps the source could be wiki but when the docs are built it could pull the .md from the wiki and build it as if it were a normal .md page in the git repo?

I'm totally open to other ideas.

Thank you!

@sgugger

[sgugger]

That's tricky. We already have way too many channels between the forums, the blog, the documentation and soon the course so I don't want to add a new one. You can create wiki posts on the forum, so maybe use that for the iterative process where you want some collaboration? We can then link those from the doc if relevant.

Down the road, once such a document is stable it should be converted in a doc page though.

[stas00]

That's tricky. We already have way too many channels between the forums, the blog, the documentation and soon the course so I don't want to add a new one. You can create wiki posts on the forum, so maybe use that for the iterative process where you want some collaboration? We can then link those from the doc if relevant.

Oh, I was thinking not to add a new channel but re-use the available ones - I was just thinking how to link it to the main docs while it's a work in progress.

I'm thinking of a much simpler approach - one of:

1. transformers github wiki - would be limited to hf members - less direct input, but easier to manage
2. forums wiki - would be open to all - but potentially require much more effort to manage
   and then linking one of these to the docs website menu - is that possible? and once the doc is strong it can migrate to a real .md doc.

Down the road, once such a document is stable it should be converted in a doc page though.

That!

[stefan-it]

Hi @stas00 ,

could maybe have a look at: https://hackmd.io/

So you can just edit your markdown/README file, invite other collaborators and when everything is ready you could open a PR for the final submission into Transformers :)

[stas00]

Thank you, @stefan-it.

It's not so much about where to collaborate on it, but how to potentially do it long term while keeping the doc easily found with all the other transformers docs, while it's a work in progress.

I think the question is simple - @sgugger - would you support linking from the https://huggingface.co/transformers/ to some docs in progress until they are mature enough to import them as a normal doc? Then we can look at what would be the easiest way to collaborate.

Or to keep things on the website, perhaps an iframe that remains on https://huggingface.co/transformers/ but includes the off-site doc? Not asking for anything complicated at all, whatever the easy/quick solution works. This is just an idea.

[stas00]

stale