How to write a Tech United Eindhoven wiki report

Transcription

1 How to write a Tech United Eindhoven wiki report D. van Ummy Bachelor Final Project Tech United Eindhoven - Wiki Report Coach(es): Supervisor: C. Oach dr.ir. S. U. Pervisor Eindhoven University of Technology Department of Mechanical Engineering Control Systems Technology Eindhoven, August, 2013

2 How to write a Tech United Eindhoven wiki report Author(s): Robin Soetens, add your name! Supervisor(s): René van de Molengraft Abstract These wiki pages serve as a template for those who write a wiki report to finish their projects at Tech United Eindhoven. It provides guidelines for the contents of the report, as well as tips and tricks for academic writing and instructions on how to efficiently use the wiki syntax. We use this type of wiki reports because it allows succeeding students on the same project to build on what is already there, while at the same time it retains the structure of a scientific report involving a problem statement, approach and results. A wiki report can be used for projects on robotic hardware design as well as projects on software development. Contents 1. Introduction 2. Obtaining Access 3. Academic Wiki Writing Instructions 4. Handing In Your Report 5. Results 6. Conclusion 7. Future Work 8. References Top - Next chapter Retrieved from " title=how_to_write_a_tech_united_eindhoven_wiki_report" This page was last modified on 26 August 2013, at 14:38.

3 Wiki Report: Introduction Documenting your work is key to whether or not other people will use it later on. Both in programming and in electrical/mechanical design, way too often wheels are reinvented because the person who did the job originally did not provide documentation. In programming useful tools exist to document the classes, functions and variables you created (e.g., Doxygen ( [1]). A platform to share robotics software with others exists as well ( [2]. Similar tools and platforms are available for hardware design ( [3]. But in order to report on the scientific contribution of your work, a different approach is needed. For student projects, reports written in LaTex ( traditionally are the most common way to report on scientific contributions. Although the layout is nice, and friendly to figures and formulas, we see a disadvantage. After grading, in most cases the hard copy report ends up in some well hidden archive. Unless a supervisor actively points someone to the report it is likely nobody uses it anymore, probably not even successor students working on the same project. A straightforward solution would be to ask students to submit a pdf of their report and put these online, such that they are indexable by the major search engines. But student projects in robotics often involve working in a large group of people, some of them focusing on strongly related topics. If everybody would create a new pdf document for each project he or she spends time on, that would result in a lot of overlap in documentation. Further, given the closed nature of pdf documents, it would be hard to keep references and other parts of the report up to date. Putting both the pdf and the LaTex source online would help, but is no comprehensive solution either. The entire document would have to be recompiled for each and every change, which could end up being a wearing job since different people use different packages and environments. Therefore we think wiki reports are the way to go with respect to student project reports at Tech United Eindhoven. Wiki pages are easy to edit by multiple people at once, which makes it easier to keep the documentation up to date and easier to use existing documentation in new reports. The syntax allows LaTex like formatting of formulas and makes it easy to link to other wiki pages or other places on the internet. Popular wiki pages will be found by search engine bots crawling the world wide web and could eventually end up in search results. Writing a wiki report is a more modern way of wrapping up your student project. Your work will be embedded in a larger body of documentation related to the specific robotic system you are working on. At the same time it is important a scientific approach of reporting results is guaranteed. Wiki reports should follow an outline similar to traditional reports. They start with an abstract and contents page, followed by an introduction that involves a clear problem statement, related work and an outline of the report. The introduction page is followed by pages describing the approach you took to solve the problem. The approach pages are followed by a page showing your results and a page with

4 conclusions and recommendations on future work. In order to make sure each page remains standalone readable, any references will be in the bottom of the page where you are referring to them, but you are also required to put all the references you have used on a separate page. Possibly this pages is followed by attachment pages containing information that might be useful but is not important enough to put in the main sections of your wiki report. This manual on how to write a Tech United Eindhoven Wiki Report follows an outline similar to what the outline of the wiki report itself should be. Thereby it provides a template for future wiki reports while providing tips and tricks on how to write such a report. The approach sections starts with a page on how to obtain access to the Tech United wiki pages, followed by general instructions on academic wiki writing and instructions on how to hand in a hard-copy version of your report. In the results section we show an example of how to include figures in your wiki report. References [1] van Heesch, Dimitri Doxygen: Source code documentation generator tool. [2] Quigley, Morgan, et al ROS: an open-source Robot Operating System. ICRA workshop on open source software. Vol. 3. No. 3.2 [3] Lunenburg, J.J.M. et al Sharing Open hardware through ROP, the Robotic Open Platform. RoboCup Symposium special track on open-source hard- and software Retrieved from " This page was last modified on 28 August 2013, at 10:05.

5 Wiki Report: Obtaining Access Tech United wiki pages are spread over two different servers. This page ( ) serves as a portal to find the pages corresponding to the project you are working on. Wiki pages starting with ' (e.g., those related to the Middle-Size League and the Humanoid team) require a different account from those starting with ' (e.g., those involving information on the AMIGO robot). Account for techunited.nl/wiki This wiki is fully open, i.e., all of the sections are readible for anyone on the world wide web (keep that in mind!). In order to edit pages you will have to log in with your TU/e student number and password. Adding a new page directly in one of the main navigation menus (Hardware, Software, Manuals etc) requires some extra user privileges. Please contact the Tech United office managers, who have an account with such privileges. Please also contact the Tech United office in case you need to edit the wiki but do not have a TU/e student account. The Tech United office can be reached via 'techunited -a-t- tue.nl', or drop by at their working spot near the RoboCup field in Gemini-North. Account for cstwiki.tue.nl The AMIGO section on the CST wiki is only readible for team members. Logging in with a TU/e account is not possible. Please contact the Tech United office managers at 'techunited -a-t- tue.nl' to obtain an account. Retrieved from " This page was last modified on 26 August 2013, at 12:32.

6 Wiki Report: Academic Wiki Writing Instructions Many documents containing tips and tricks for academic writing already exist [1,2,3]. These are also useful in writing a wiki report. Here ( you find a useful introduction to the wiki syntax. Other important things to keep in mind are: Each of the pages in the body section of your wiki report should be stand-alone readable. Make sure that each symbol you are using in formulas is introduced on the page you are using it, or clearly refer to the page where it is introduced. Use many crosslinks to direct readers to places where they can find more information. Link to other Tech United wiki pages, but also to other places on the internet if you think there is a benefit in that for readers. Same as writing a wiki page ( not related to Tech United, make sure that your writing is supported by strong references to other academic work. Use the <math> environment to include mathematical expressions on the Tech United wiki pages. Within this environment you can use the same syntax ( you would also use to include equations in a LaTex document. Use this tool ( if you have an operator you do not know the corresponding LaTex expression for. As said before, the body part of the wiki report can contain pages you have edited but not entirely written by yourself. When handing in a hard-copy version of your report for grading it should be clear what exactly is your contribution (more on this in the section on handing in your report). For the sake of maintaining a solid flow within the report, please make sure that each of the pages really contribute to solving the problem you have stated in the introduction. If you made significant contributions to general wiki pages/tutorial you would like to include in grading, please add them as an attachment. The type of wiki we are using is MediaWiki ( Please contact the Tech United office managers in case you think you need any of the extensions listed on their website. Together with 'webadmin -a-t- tue.nl', the office managers are able to install things on the back end of the wiki.

7 References [1] Scott A. Socolofsky, 2004 How to write a research journal article in engineering and science. Link ( [2] Writing tips for student reports Link ( title=writing_tips_for_student_reports) [3] Ten tips for your thesis Link ( Retrieved from " title=wiki_report:_academic_wiki_writing_instructions" This page was last modified on 28 August 2013, at 09:38.

8 Wiki Report: Handing In Your Report The body part of the wiki report can contain pages you have edited but not entirely written by yourself. When handing in a hard-copy version of your report for grading it should be clear what exactly is your contribution. Therefore when handing in a pdf or hard-copy version of your wiki report we kindly ask you to clearly indicated the sections you have edited in case a page has multiple people as author (by turning them a different color for example). Here ( you find a LaTeX template that could be useful when adding each of the wiki pages to a single pdf ( with titlepage. This example has been made by merging pdf's that were printed directly from the wiki page. Using tools like Pandoc ( it is possible to convert wiki syntax to LaTeX syntax, which would lead to a more neat document. Bachelor Final Project / Schakelprogramma Final Project Provide your supervisor with a hard-copy version of your report and submit a pdf version of the report to the faculty via 'werktuigbouwkunde -a-t- tue.nl'. Any code or video files you would like to include can be added as a zip file attachment. You will also have to fill this questionaire ( and submit it to the faculty via the address mentioned above. Master Free Space Project Unless specified otherwise, sending a digital pdf of your report to your supervisor should suffice. Retrieved from " title=wiki_report:_handing_in_your_report" This page was last modified on 28 August 2013, at 11:18.

9 Wiki Report: Results In the results section you should show whether or not you have managed to solve the problem stated in the Figure 1. Dummy plot for How to write a Tech United wiki report introduction. Results should be clearly measurable and should be compared to previous work by others. Some tips and tricks to make a wiki results page: Use this page ( to upload images to the techunited.nl/wiki server, use this page ( title=special:upload) to upload images to the cstwiki.wtb.tue.nl server. Only.png.gif. and.jpg files can be uploaded. Here ( you find instructions on layout for figures on wiki pages, here ( a more detailed one. In the body text of the results page, make sure to refer to each of the figures you are using. On this page we have provided a dummy example (Fig. 1). Add labels to your plots, and a caption to the figure.

10 Retrieved from " This page was last modified on 28 August 2013, at 10:12.

11 Wiki Report: Conclusion We have presented a template for a wiki report. Using wiki instead of traditional LaTeX reports, it will be easier for others working in the same field to find and use your work. Retrieved from " This page was last modified on 28 August 2013, at 10:07.

12 Wiki Report: Future Work Some things that can be improved with respect to this wiki and the wiki report template: Install a wiki extension for more BibTex like formatting of references. For example any of the templates mentioned here ( Experiment with Pandoc ( and other tools to automatically convert LaTeX syntax to wiki syntax. Possibly in the future a wiki report can follow directly from a LaTeX report and vice versa. Find a way to easily embed video's in wiki pages. Retrieved from " This page was last modified on 28 August 2013, at 11:20.

13 Wiki Report: References References Introduction [1] van Heesch, Dimitri Doxygen: Source code documentation generator tool. [2] Quigley, Morgan, et al ROS: an open-source Robot Operating System. ICRA workshop on open source software. Vol. 3. No. 3.2 [3] Lunenburg, J.J.M. et al Sharing Open hardware through ROP, the Robotic Open Platform. RoboCup Symposium special track on open-source hard- and software References Academic Wiki Writing Instructions [1] Scott A. Socolofsky, 2004 How to write a research journal article in engineering and science. Link ( [2] Writing tips for student reports Link ( title=writing_tips_for_student_reports) [3] Ten tips for your thesis Link ( Contents Retrieved from " This page was last modified on 28 August 2013, at 09:29.