search

ieeecs / seradio-manual

Host manual for the Software Engineering Radio
16 stars 4 forks source link

Manual in wiki format #1

Closed fedy2 closed 7 years ago

fedy2 commented 7 years ago

Would be nice to have the manual in wiki format so other people can contribute to it. The wiki format would help also the translation to other languages.

RobertBlumen commented 7 years ago

@fedy2 I see the benefits of this idea. By wiki format do you mean one of the existing wiki markups such as wikitext or the format used by MediaWiki? Or do you mean a hosted wiki site with the manual as a page on the site? Currently I am not aware that the computer society has a hosted wiki that could be opened to the public.

RobertBlumen commented 7 years ago

@fedy2 second question - The source of the document is now a Google doc, which changes on a monthly basis. I have done conversions from an office-type doc to a markup language before, never with very good results. There is usually an automated step that does 70% and 30% manual cleanup required. I wouldn't mind doing this once but from that point forward I really have two sources that would need to be maintained in parallel. If there is a fully automated reliable and accurate conversion then I could do the conversion a few times per year and merge the diffs. Do you have experience with any automated and accurate conversions from Google docs to wiki markup?

fedy2 commented 7 years ago

Yes I mean markdown format. It is supported by GitHub and can be edited directly on the GitHub site. Is the same format used for the readme file in the repository. Here a similar project: https://github.com/johnpapa/angular-styleguide

fedy2 commented 7 years ago

About the second question: I don't know any automated tool for conversion between Google doc and markdown. The idea of using the markdown format is a way to let other people collaborate to the manual using the git repository in GitHub. I think would be complex to keep a separate google doc copy where you have to copy the users suggestions/modifications.

RobertBlumen commented 7 years ago

ok - within the next few months, or, when I can get to it, I will make an attempt to export the google doc to a markdown.

molk commented 7 years ago

please consider asciidoc instead of markdown. please ...