[James Ross]

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.

[cjakeman]

SD45T-2, on 09 May 2020 - 05:30 PM, said:

Would sometime next week be good? I'm the one who started the thread, may as well continue with it.

Yes, please, and thanks.

Just send me a private message (PM) when you're ready.

[xavivilla]

I hope they continue with reStructuredText/Sphinx files in the preparation of the manual, it is more convenient than Microsoft Word to locate the modifications and new texts in the manual and to translate it into my native language.

[R H Steele]

James Ross, on 10 May 2020 - 02:40 AM, said:

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.

Noted, was unaware of this link, thank you. Still thinking about how to help out. Maybe clean up the office after all the developers leave for the day. http://www.elvastower.com/forums/public/style_emoticons/default/sign_rockon.gif http://www.elvastower.com/forums/public/style_emoticons/default/biggrin.gif

[markus_GE]

cjakeman, on 09 May 2020 - 09:39 AM, said:

[...]
I think that what we lack is a good set of instructions that show:

• How to pull down the latest version of Open Rails from the GitHub repository,
• How to make an edit
• and re-build the PDF so you can see the result of your work.
• How to push your work back to GitHhub
• and request that it be reviewed and pulled into the Testing version.

[...]

Trying not to sound like a know-it-all, but couldn't the step-by-step guide you provided when I asked about an introduction to Git for translation purposes be re-used for steps 1, 4 and 5? Or would working on the manual require the use of branches?

Cheers, Markus

PS: I've not forgotten about our collaboration on a translation guide, it's just that I'll take my last exam from my BSc's studies on MAY-18. Thus, electrical engineering tends to occupy most of my days currently.