Elvas Tower: Helping with the manual. - Elvas Tower

Jump to content

  • 2 Pages +
  • 1
  • 2
  • You cannot start a new topic
  • You cannot reply to this topic

Helping with the manual.

#11 User is online   James Ross 

  • Open Rails Developer
  • Group: Status: Elite Member
  • Posts: 5,186
  • Joined: 30-June 10
  • Gender:Not Telling
  • Simulator:Open Rails
  • Country:

Posted 10 May 2020 - 02:40 AM

View Postmrmosky, 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.

View Postmrmosky, 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.

View PostR 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.

#12 User is online   cjakeman 

  • Superintendant
  • PipPipPipPipPipPipPip
  • Group: ET Admin
  • Posts: 1,926
  • Joined: 03-May 11
  • Gender:Male
  • Location:Peterborough, UK
  • Simulator:Open Rails
  • Country:

Posted 10 May 2020 - 02:45 AM

View PostSD45T-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.

#13 User is offline   xavivilla 

  • Hostler
  • Group: Status: Active Member
  • Posts: 83
  • Joined: 12-May 12
  • Gender:Male
  • Simulator:Open Rails - RailWorks
  • Country:

Posted 10 May 2020 - 06:20 AM

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.

#14 User is offline   R H Steele 

  • Vice President
  • PipPipPipPipPipPipPipPip
  • Group: ET Admin
  • Posts: 2,484
  • Joined: 14-March 13
  • Gender:Male
  • Location:known universe
  • Simulator:Open Rails
  • Country:

Posted 10 May 2020 - 07:17 AM

View PostJames 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


#15 User is offline   markus_GE 

  • Executive Vice President
  • PipPipPipPipPipPipPipPipPip
  • Group: ET Admin
  • Posts: 4,623
  • Joined: 07-February 13
  • Gender:Male
  • Location:Leoben, Styria, Austria, Europe
  • Simulator:ORTS / MSTS
  • Country:

Posted 10 May 2020 - 03:47 PM

View Postcjakeman, 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.

  • 2 Pages +
  • 1
  • 2
  • You cannot start a new topic
  • You cannot reply to this topic

1 User(s) are reading this topic
0 members, 1 guests, 0 anonymous users