mrmosky, on 09 May 2020 - 09:15 AM, said:
As an observer, it seems to me that there are two skill sets required here. One is the skill to do technical writing, and the other is skill with several software tools.
I think it depends.
If you're writing a complex section of the manual, with tables, figures, and such, you will need to be able to build the manual to validate that you've got it right. There are plug-ins for editors that can help with this.
But if you're fixing a mistake, or adding a simple paragraph here or there, you would be fine to use the "Edit" button on the GitHub site. It'll walk you through to a PR.
mrmosky, on 09 May 2020 - 09:15 AM, said:
Wouldn't it be possible to split these up between two people? Someone who is a good technical writer could produce a manual section in whatever word processor they are comfortable with, and then a second person could easily cut and paste that text into the correct language for the manual.
You could certainly collaborate like that, but I'd recommend at least trying GitHub's built-in editing as an option.
R H Steele, on 08 May 2020 - 07:21 PM, said:
First, I am assuming there probably was or still is a very good reason to use the method you outlined...that I have no clue about.
As with everything, there are pluses and minuses for both the original Word file we used, and the new reStructuredText/Sphinx we use now.
The Word file was easy for someone to simply open up and start making changes, with a nice WYSIWYG interface, but it was troublesome to merge those changes back in if others had also made changes, and the formatting was very messy at times. We could generate a PDF from it.
The reStructuredText/Sphinx files are much easier to merge multiple people's changes to together and solve the messy formatting issue, but you need to install a couple of tools to build/preview changes. We can generate a PDF from it, but we can also generate a beautiful website.