search

manubot / rootstock

Clone me to create your Manubot manuscript
https://manubot.github.io/rootstock/
Other
453 stars 178 forks source link

Defer ai-editor documentation to dedicated repo #511

Closed vincerubinetti closed 4 months ago

vincerubinetti commented 5 months ago

yes, please hold off on merging. We still need to work on the documentation in the editor repo some more

agitter commented 5 months ago

@vincerubinetti do you think the USAGE.md here has gotten too long and complex? The AI workflow is part of this repo, so I'm wondering about the motivation for moving the documentation. I'm not against it but want to understand your thought process. about how we'll manage these.

Making sure @miltondp sees this too.

vincerubinetti commented 5 months ago

Milton is aware; it may have been his suggestion iirc.

I think the idea is just that the AI editor is a somewhat complex and separate thing. As a comparison, you do have detailed instructions about how citations work, which could perhaps be deferred to documentation in the python package for collocation. But in that case, citations are really the bread and butter of Manubot, whereas less people would use the AI editor.

Perhaps more importantly, since the AI editor is still early in its development and changing a lot, it might make for a cleaner commit history here. While developing/maintaining lab-website-template (a similar case to rootstock, where it's not an installable "package" but rather a template), I try to be wary of frequently changing files, as merging in upstream updates can be a painful process, especially for less technical users.

I don't feel strongly about this though. The writing I added could stand as is, and we could keep the stuff I removed.

agitter commented 5 months ago

Thanks, that's helpful. If the ai-revision.yaml workflow was going to have frequent updates anyway, then it would make sense to keep the corresponding detailed documentation here. However, that workflow file is fairly straightforward so most updates will likely happen in the manubot-ai-editor repo. I lean toward making this change.

miltondp commented 4 months ago

The team working on the Manubot AI Editor decided it would make more sense to have its documentation on a repo that we control more directly, and we also discussed several of the reasons @vincerubinetti already mentioned. As the Manubot AI Editor code stabilizes, we can decide how to proceed, but for now I would move the documentation. The merging should happen when we have the documentation ready on the manubot/manubot-ai-editor repo.

vincerubinetti commented 4 months ago

Now that https://github.com/manubot/manubot-ai-editor/pull/42 is merged, I think this is ready to merge.

vincerubinetti commented 3 months ago

Followup: https://github.com/manubot/manubot-ai-editor/pull/44