Wiki-based Software Documentation [Ademar Aguiar], [Gabriel David] {link: FEUP|http://www.fe.up.pt} and {link: INESC Porto|http://www.inescporto.pt}, {link: University of Porto|http://www.up.pt}, Portugal ---- __Tuesday, October 18, 2005, 1:30-5:00 pm, in the Esquire__ A space to share your opinions and ideas about using wikis for documenting software. [Ademar Aguiar] ---- 1.1 Contents * {link:Introduction|http://wiki.wikisym.org/space/Wiki-based+Software+Documentation#_Introduction} * {link:Goals|http://wiki.wikisym.org/space/Wiki-based+Software+Documentation#_Goals} * {link:Main theme|http://wiki.wikisym.org/space/Wiki-based+Software+Documentation#_MainTheme} * {link:How to Participate?|http://wiki.wikisym.org/space/Wiki-based+Software+Documentation#_Admission} * {link:Workshop preparation|http://wiki.wikisym.org/space/Wiki-based+Software+Documentation#_Preparation} * {link:Workshop activities and format|http://wiki.wikisym.org/space/Wiki-based+Software+Documentation#_Format} * {link:Agenda |http://wiki.wikisym.org/space/Wiki-based+Software+Documentation#_Agenda} * {link:Post-workshop activities|http://wiki.wikisym.org/space/Wiki-based+Software+Documentation#_PostActivities} * {link:Organizers|http://wiki.wikisym.org/space/Wiki-based+Software+Documentation#_Organizers} * [Workshop notes|Workshop2Documentation_Notes] 1 {anchor: Introduction} Introduction Wikis proved to be very appealing collaborative tools to present and edit web-based information, using a __very simple markup language__, a __powerful dynamic-linking mechanism__, and support to __adaptive web pages__. This workshop aims at bringing together __researchers, practitioners and tool developers__ interested in researching and exploring wikis as collaborative tools to support software development, in concrete for cost-effective software documentation. 1 {anchor: Goals} Goals The main goals of the workshop are the following: * to identify key __obstacles, opportunities, and challenges__ to wiki-based software documentation * to plan the writing of a __review/survey article__, or a monograph, on the topic * to envision an __ideal wiki for software documentation__ in order to plan developing one * and to build possible __collaborations for future research and development__. 1 {anchor: MainTheme} Main theme It is commonly accepted that good documentation benefits every software development project but its production and maintenance often consume a lot of development effort, especially when not done with appropriate tools and methods. 1.1 Programming and documenting is hard? In addition to the highly demanding activities of programming, developers are often forced to contribute to several kinds of documentation (user documentation, architecture and design documentation, and internal documentation) in order to preserve and communicate the understanding they have about the software system under development. The inadequacy of documentation techniques and tools ends up introducing difficulties: * on the overall development process * on the continual review and modification of documents throughout their life cycle * and on preserving the consistency between the different kinds of artifacts involved (documents, source code and models), issues that often compromise the programming productivity and/or the documentation quality. Because to document is hard, and developers don?t see short term benefits on it, they often simply focus on programming, unless mandated, thus letting documentation almost neglected. 1.1 Wikis are very appealing documenting tools Wikis proved to be very appealing collaboration tools to present and edit web-based information, providing a __very simple markup language__, a __simple but powerful dynamic-linking mechanism__ based on lexical conventions, and its ability to __support the notion of adaptive web pages__. Wiki documents are: * open * can be evolved incrementally and organically * are easy to edit and organize * promote convergence of contents and consistency of terms, * are tolerant, * and are easily observable by other users. Due to their qualities and attractiveness, wikis are now widely spread on the web, especially in the software community, run on many different platforms, and are being used to serve different kinds of contents and documents of different knowledge domains. 1.1 Strengths and weaknesses of wikis for documenting software As said before, this workshop focuses on the usage of wikis as tools for collaboratively editing software documentation. There are many wiki sites being used to cooperatively develop software documentation, such as ([Workshop2WikiExamples]): * drafts of designs and implementations * design discussions, * requirements gathering * (please add here more kinds of document...) However, there are still several open issues that would benefit from further research and development in order to leverage wikis to a wider and more effective usage as a tool for software development. In fact, despite the richness and variety of the wikis available, only a few incorporate features specific to support software documentation: * bug tracking * tests * language-specific source code formatting * simple models * dynamic-linking to source code repositories, such as version-control systems * integration in open development environments * (please add here more features...) Although its current limitations for satisfying all the specific requirements of documenting software, wikis are already very helpful on supporting the collaborative edition and maintenance of software documentation, but much more can be probably done with a wiki in order to make them an unavoidable tool in software development. In this workshop we will try to __explore, discover, and understand__ the present limits of wikis to support software documentation, and to gather __new ideas__ and __challenges__ possibly to be addressed in future __research and development on wiki technology__. 1 {anchor: Admission} How to Participate? We?re interested in exploring wikis as a tool to support cost-effective software documentation. We are also interested in a lively debate. So, if you want to learn more about this topic or to share your research work, experience and ideas related with using wikis as a supporting tool to document software, you must participate. In respect to software documentation, we think that wikis are good for: * gathering, relating, developing, maintaining, and presenting software documents (requirements, design models, programs, tests, bug reports, etc), * combining multiple kinds of contents (source code, models, structured text, free text, etc.), manually or automatically produced with software engineering tools. Examples of relevant topics include, but are not limited to: * report of experiences using wikis to support software documentation * key features of wikis for software development * specific markup languages for software documentation contents * integration of wikis with software engineering tools (IDE?s, test tools, Q&A tools, version-control systems, etc.) * integration of wikis with project management tools (communication tools, workflow systems, etc.) * semantic preservation mechanisms between source code, models, and wiki-based documents * wikis as a front-end for content management systems for software documentation * (please add here your favorite topics) Add a short biography (1 paragraph is ok) to let us all know a little more about you. Share also your ideas, expectations or experiences responding to this call for participation in [Workshop2Contributions]! (see how below) 1 {anchor: Preparation} Workshop preparation No special preparation is required to attend the workshop, but we would like to invite the attendees to contribute to the workshop by sharing their experiences, ideas, and expectations related with using wikis as a tool for documenting software in a cost-effective way. This wiki of WikiSym is available for pre-, during, and post-workshop use. A login and password are required to edit the wiki, but if you don?t have an account you can register or use the account provided by the workshop to log in as a ~~Workshop2Participant~~ and share your ~~contribution~~ in [Workshop2Contributions]. If you still need to know the user and password, please send an email to ademar.aguiar at fe.up.pt. 1 {anchor: Format} Workshop activities and format This will be a 3 hours workshop on __Tuesday, October 18, 2005, 1:30-5:00 pm, in the Esquire__. There will be perhaps 1 or 2 small formal presentations: an introductory one, to define the context, goals and expected results of the workshop, and a more visionary one to promote discussion and to push the limits of wikis as a documentation tool for software development environments. As the goal is to __explore, discover and understand__ the strengths and weaknesses of wikis for software documentation, we plan to do this by brainstorming sessions. We will probably set up a wiki during the workshop to take notes and for additional interactivity. The workshop will be formatted according to the number of participants, but it will include a small introduction, a summary of the contributions and ideas gathered before the workshop, and organized discussions in workgroups about the theme of the workshop to draw possible future collaborations and research and development agendas. 1.1 {anchor: Agenda} Agenda Here is an initial agenda: * 1:30?2:0pm: Welcome. Summary of goals, contributions, and present state of the art and practice on wiki-based software documentation. * 2:00?3:00pm: Exercises and discussion. ([Notes|Workshop2Documentation_Notes]) * 3:00?3:30pm: Break (optional :-)) * 3:30?3:40pm: "The ideal wiki for software documentation", a visionary talk. * 3:40-4:40pm: Exercises and discussion. * 4:40?5:00pm: Consolidation and closing. 1 {anchor: PostActivities} Post-workshop activities The wiki (this or another one) will be kept alive after the workshop in hopes of continuing the discussion and collaboration. We hope to write a review or survey paper on the topic after the workshop in collaboration with the participants interested on co-authoring it. 1 {anchor: Organizers} Organizers [Ademar Aguiar] teaches at Faculty of Engineering of University of Porto (FEUP) and does Research & Development at INESC Porto. He has specialized in the area of software engineering, mainly framework technology, design patterns, agile processes, and software documentation. Currently, his main line of research is on the development of a pragmatic approach to document object-oriented frameworks, which comprises a documentation model, an agile documentation process, and a set of collaborative documentation tools and utilities based on the WikiWikiWeb concept and XML technologies. [Gabriel David] teaches at Faculty of Engineering of University of Porto (FEUP) and does Research & Development at INESC Porto. He has specialized in the area of large information systems, mainly business modeling, database systems, and university information systems, topics about which he has authored several research papers. 1 {anchor: Participants} Participants [Ademar Aguiar] [Costin] [DJ] is a software developer at Microsoft. Works in a group of 100+ developers that are contributing to wiki software documentation. [Uri Dekel|UriDekel] is a PhD student at Carnegie Mellon University. Interested in using Wikis to support capture and documentation of the initial and informal software design during design meetings. [Angel Palazon] [Tim|tbonnemann] [Frank] [Matthias Jugel] Ademar Aguiar Ademar Aguiar 2005-10-19 19:58:16.232 2005-09-05 15:29:37.536 comment-Wiki-based Software Documentation-1 Hi, I would like to attend the conference but unfortunately am unable. I am interested in these kinds of tools and have written two documentation based tools for Eclipse: http://eclipsewiki.sourceforge.net and the experimental Subtext (http://www.stateofflow.com/projects/12/subtext) - a bit dead at the moment. Subtext uses an aspect-like language to present documentation relevant to the user in the current context. Presenting documentation relevant to the user when it matters will help to bring the documentation alive and may engage the interest of developers more. The Mylar project (http://www.eclipse.org/mylar/) might provide some useful infrastructure to support this: ~~Mylar monitors programming activity, actively searches for related elements, and extends the Eclipse UI to focus on the elements of interest.~~ Channing 2005-10-09 21:51:02.896 2005-10-09 21:51:00.472 comment-Wiki-based Software Documentation-2 Hi Channing! Thanks for your comment and your interest on the subject. I know your work, specially the http://eclipsewiki.sourceforge.net/ so I will add references to it in these pages, or you can do it yourself in [Workshop2WikiExamples] and [Workshop2Contributions]. Let's keep in touch! -- [Ademar Aguiar] Ademar Aguiar Ademar Aguiar 2005-10-10 10:24:36.4 2005-10-10 10:24:32.072 comment-Wiki-based Software Documentation-3 Hi Ademar, I see you've already a link to the EclipseWiki. A feature I get asked for quite often is to be able to embed Wiki docs in Javadoc. I haven't had a chance to do it yet but it could be an interesting way of coupling 'higher level' documentation with implementation. Channing 2005-10-10 21:35:59.512 2005-10-10 21:36:06.352