Algorithms/Guidelines for Contributors
Appearance
Introduction to the Series
[edit | edit source]This book is part of a series of three text books on data structures and algorithms:
- Data Structures—A book suitable for a first course in data structures that presents the most common data abstractions and their construction and properties. A tutorial on the most key points.
- Algorithms—A book suitable for a first course in algorithms that presents the most common algorithmic techniques and how to analyze algorithms. Assumes some knowledge of data structures. A tutorial on the most key points.
- Advanced Data Structures and Algorithms—A book that covers more advanced material that assumes some prior knowledge of data structures and algorithms. While the first two books are tutorials, this book is more reference based. Thus, its content can be much more eclectic. Advanced (and interesting) material that doesn't fall into the tutorial nature of the first two books belongs in this book.
The reason these books are in a series is to help narrow their focus and to aid coordination of the efforts. An eventual goal is that books will be available for every computer science subject.
Guidelines
[edit | edit source]- If you want to fix a bug, simply click on "edit", make your changes, and click on save. We'll review the changes to be sure they are appropriate for the book. If you are unsure, you can visit the "discussion" page and ask there. In general, to make a small change, you don't need to ask first, and you can just use common sense to determine if your change is appropriate.
- If you would like to write a chapter, section, or part of a section, take a look at the items marked with "TODO" tags and start there.
- Be sure to read all other sections of the book first in order to avoid duplication of content.
- When writing a section, you can mark some parts as "[TODO: explanation]", where explanation describes what you intend to take place in that part. For example, if you aren't good at making images, you can make as a TODO item a description of the image that should go there. Perhaps someone who is effective at making images will notice this and provide one for you. The purpose of a TODO item is to give the plan of what should be written.
- This is a tutorial: We aren't aiming to create an encyclopedia of every algorithm ever created, nor are we trying to present the absolutely best versions of particular algorithms.
- Don't include links to wikipedia articles in the book's chapters: The idea is that each book is self-contained so a reader can print out the book and read it separately, instead of having to navigate through it online.
- The book uses a pseudocode language that should be familiar enough to those who know Algol-family languages (including C, Java, Pascal, and Python). It includes extra features that help abstract away nitty-gritty implementation details, and thus allows for the real algorithmic idea to be communicated, rather than focusing on the trivial implementation issues that are language dependent.
- Implementations in non pseudocode can be written for an appendix. These implementations can serve to be usable by readers and to make clear any possible ambiguities. Implementations should be tested well and include test cases. Implementation languages are Python, C, Java and Scheme.
- Put a star ("*") next to section or sub-section titles if the material presented there isn't essential to understanding the larger point of the chapter. (For example, a more junior reader might elect to skip or skim these sections.)
- Use primary sources when possible. If you do use a reference, put it on the references section. Never copy content without asking permission. Further, note that even some GFDL content uses a different license version (not all are forward compatible, either) and should not be copied without permission.
- Use the wikipedia as another source for material, but edit the material to present only the main points and ideas: the encyclopedic detail of the wikipedia can become a distraction when trying to learn just the basic concepts.
- Use the mathematical royal "we" for some phrases, but try to use the second-person "you" as much as possible: it makes sentences easier to construct that also sound more direct.
- Look for insights into understanding an algorithm or a part of the software engineering process in general.
- Avoid using the passive voice ("The article was written by us."). Instead, try to use the active voice ("We wrote the article.").
- Don't use "this" as a pronoun, only use it as an adjective.
Development Phases
[edit | edit source]- A table of contents should be created and more or less agreed upon. Such a table will set the scope for the book. Changes, of course, can be made later. ( DONE: The TOC is more or less agreed upon by contributors)
- After the chapters are broken up, the sections and subsections should be designed, with TODO items describing the content to go in that place. ( DONE)
- The most important concepts should be written first, to provide an anchor and context for the other material to be built from. ( IN PROGRESS: Join us!)
- Implement C, Java, Python and Scheme versions of the algorithms and put them in the appendixes. ( Still TODO...)
- Similar to an open-source project, more and more "features" (i.e., chapters and sections) should be added. This stage will happen after the First Edition milestone is met. However, when making improvements for the second edition, core items shouldn't be neglected. ( Still TODO...)
Writing a book takes time and dedication, but if you've come this far, it's probably going to be worth it. Just as free software programs don't simply drop from the tree, whole open books won't write themselves.