open-advice / open-advice

the Open-Advice book

Open Advice

This is the repository for the Open Advice book. You can find the LaTeX source of the book here.

Building a PDF

To build a pdf file out of the LaTeX source install pdflatex and run the command

make

If you don't have make, you can run:

pdflatex Open-Advice

To build all other formats run:

make all

Updating the book after changes

If you have made local changes to the source of the book and want to render a PDF again:

make clean
make

Installing pdflatex

On Debian-based systems, you can install "pdflatex" with:

sudo apt-get install texlive-latex-extra

On Gentoo-based systems, "pdflatex" and required extra pacakges can be installed with:

emerge texlive-latexrecommended xcolor

Issues

"File `todonotes.sty' not found."

This means you need to run the above apt-get command, because you are missing one of the LaTeX extra packages.

"File `tocstyle.sty' not found."

If your distro doesn't have that you can download it from http://www.tug.org/texlive/devsrc/Master/texmf-dist/tex/latex/koma-script/tocstyle.sty and place it in the root directory of the book.

Project Statistics

Project activity is tracked by ohloh.net - see https://www.ohloh.net/p/open-advice-the-book for details.

Referencing This Book

To reference this book, you may use the following Bibtex citation:

@book{Greve2012,
author = {Greve, Georg and Hemel, Armijn and Prodromou, Evan and Kr\"{o}tzsch, Markus and Ortega, Felipe and Hawthorn, Leslie and Ottens, K\'{e}vin and Pintscher, Lydia and Mitchell, Jeff and Appel, Austin and Macieira, Thiago and Bergius, Henri and Blin, Kai and Pulido, Ara and Klapper, Andre and Leto, Jonathan and Jha, Atul and Bowen, Rich and Gentle, Anne and McCance, Shaun and Bhattacharjee, Runa and Paumier, Guillaume and Quintero, Federico Mena and Strode, M\'{a}ir\'{\i}n Duffy and Trounev, Eugene and Kaye, Robert and Bacon, Jono and Leisse, Alexandra and Riddell, Jonathan and May, Thom and Untz, Vincent and Jarvis, Stuart and Poortvliet, Jos and Khudairi, Sally and Plunkett, N\'{o}ir\'{\i}n and Neary, Dave and Greenaway, Gareth J. and Deckelmann, Selena and Adam, Till and Karlitschek, Frank and Daffara, Carlo and Jaeger, Till and Coughlan, Shane},
editor = {Pintscher, Lydia},
isbn = {9781105514937},
keywords = {foss,open source,oss},
pages = {1--310},
title = {{Open Advice: FOSS: What We Wish We Had Known When We Started}},
url = {http://open-advice.org/},
year = {2012}
}

License

The book and its content is licenced under CC-BY-SA. For questions about the book contact Lydia Pintscher at [email protected].

open-advice's Issues

Page 30 Typo - You’ll Eventually Know Everything They’ve Forgotten

In the start of the second paragraph on that page, the text reads "When you first start of cycling, you will not even know what ques-tions to ask and you will only find out by having sore knees, aching lungs and a twinge in your back."

of should be off

Didn't notice this in the corrected issues and confirmed still there in the latest download off the site. Not sure how to fix it myself, sorry.

Link to "Cathedral and Bazaar" breaks when copied and pasted

Page 19 - 4. Prepare for the Future: Evolution of Teams in FLOSS, first footnote:

Displayed link:
http://www.catb.org/~esr/writings/cathedral-bazaar/cathedral-bazaar/

Copied link:
http://www.catb.org/%20~%20esr/writings/cathedral-%20bazaar/cathedral-%20bazaar

System: Windows 7 x64, Foxit Reader 5.0.1.0523, Chrome Browser 18.0.1025.11 beta-m

Participle of "build" is "built" (page 117)

"Translators could then work unhindered until the translation deadline, after which they would be marked as stable in the main repositories and eventually packages would be build."

should be

"Translators could then work unhindered until the translation deadline, after which they would be marked as stable in the main repositories and eventually packages would be built."

Split paragraph before conclusion list in “Evolution of Teams in FLOSS”

In “Prepare for the Future: Evolution of Teams in FLOSS”, I believe the paragraph before the list of conclusions should be split in two.

Specifically, I believe the last sentence should be in a paragraph of its own, as it does not relate to the rest of the paragraph.

In fact, I think it makes sense to also put a “Conclusions” header before that sentence, as it introduces a list of conclusions that are based on the whole chapter so far, with all its subsections (each of which is currently preceded by a header).

So, I’m suggesting switching:

[…] over by other developers staying in the community. Only in those
cases in which the package was not useful anymore it was simply
abandoned. I think we can learn some useful conclusions from these
research works:

1. Spend some time to develop the main guidelines of your project. […]

to

[…] over by other developers staying in the community. Only in those
cases in which the package was not useful anymore it was simply
abandoned.

Conclusions

I think we can learn some useful conclusions from these
research works:

1. Spend some time to develop the main guidelines of your project. […]

do not involved --> do not involve (page 235)

In page 235, just before the last paragraph,

"With a little imagination, you can come up with events that do not involved loud music and alcohol. Other types of social events
can work just as well, and be even more fun."

should be

"With a little imagination, you can come up with events that do not involve loud music and alcohol. Other types of social events
can work just as well, and be even more fun."

2 corrections

1. Shaun McCance: Stop Worrying and Love the Crowd

is:
It was the most productive I had ever seen our documentation team.

could be:
It was the most productive I had ever seen from our documentation team.
1.
Guillaume Paumier: Learn from Your Users

is:
But let's face it: if you are reading this, you are not your regular user.

could be:
But let's face it: if you are reading this, you are not our regular user.

As an abstract noun, 'technology' shouldn't have the article 'the' (page 102)

I know this isn't a big issue, but I think the difference it makes is significant, because it sounds much more natural. Abstract nouns don't have article in English, and thus

"I met brilliant people for whom the technology was a tool to accomplish something non-technical."

should be IMHO

"I met brilliant people for whom technology was a tool to accomplish something non-technical."

Regards,

David Gil

cover design needed

We need someone to design a nice cover for the book.

Typo in code/HenriBergius.tex

line 53: venture-funded efforts where going on everywhere.

"where" should be "were"

feature: add commas in title

in: Máirín Duffy Strode: Don’t Be Shy

How about changing title from:
Help the project help you help them

to:
Help the project, help you, help them

could help making people understand faster

Lulu link broken on website

The Lulu link on Open Advice website doesn't work.

This seems to be a functioning URL: http://www.lulu.com/shop/lydia-pintscher/open-advice/paperback/product-18889265.html

thank you page needed

I need to add a page for thank yous to editors, designers and so on.

cover text needed

Write the text for the back of the book.

it's --> its (page 70)

Page 70:

"The other lines are helping the patch tool to do it's job."

should be

"The other lines are helping the patch tool to do its job."

Regards,

David Gil

Could you maintain a bibtex file

I'm a student. And I find there are two many authors here, I don't want to copy all the names from your webpage. Thanks

! LaTeX Error: File `tocstyle.sty' not found.

The following error was thrown when I issued the make command,

! LaTeX Error: File `tocstyle.sty' not found.

Type X to quit or to proceed,
or enter new name. (Default extension: sty)

Website: Missing "Donate" button

Thank you for the open book. It would be really great if the web site would have a "donate" button. I don't want to kill a tree to say thank you to the authors. Any chance of getting that option?

In Debian the pdf gives numerous errors and then opens up .

Hi all,
I'm getting errors like this when parsing the pdf within Debian. It renders but there are errors :-

Error (87): Illegal character <3f> in hex string
Error (88): Illegal character <78> in hex string
Error (89): Illegal character <70> in hex string
Error (92): Illegal character <6b> in hex string
Error (94): Illegal character <74> in hex string
Error (98): Illegal character <67> in hex string
Error (99): Illegal character <69> in hex string
Error (100): Illegal character <6e> in hex string
Error (101): Illegal character <3d> in hex string
Error (102): Illegal character <27> in hex string
Error (103): Illegal character <27> in hex string
Error (105): Illegal character <69> in hex string
Error (107): Illegal character <3d> in hex string
Error (108): Illegal character <27> in hex string
Error (109): Illegal character <57> in hex string
Error (111): Illegal character <4d> in hex string
Error (113): Illegal character <4d> in hex string
Error (114): Illegal character <70> in hex string
Error (117): Illegal character <68> in hex string
Error (118): Illegal character <69> in hex string
Error (119): Illegal character <48> in hex string
Error (120): Illegal character <7a> in hex string
Error (121): Illegal character <72> in hex string
Error (123): Illegal character <53> in hex string
Error (124): Illegal character <7a> in hex string
Error (125): Illegal character <4e> in hex string
Error (126): Illegal character <54> in hex string
Error (128): Illegal character <7a> in hex string
Error (129): Illegal character <6b> in hex string
Error (133): Illegal character <27> in hex string
Error (134): Illegal character <3f> in hex string
Error: Unknown character collection 'Adobe-'
Error: Unknown character collection 'Adobe-'
Error: Unknown character collection 'Adobe-'
Error: Unknown character collection 'Adobe-'
Error: Unknown character collection 'Adobe-'
Error: Unknown character collection 'Adobe-'
Error: Unknown character collection 'Adobe-'
Error: Unknown character collection 'Adobe-'

Now I have no idea whether it is the poppler library which is at fault or the pdf . Please lemme know if any more info. would help you to narrow it down.

Whether to use --- or --

The text I have reviewed so far consistently uses -- (a short 'n' dash), where --- (a long 'm' dash) should be used. For instance:

'A freshly baked loaf -- or indeed a freshly baked cake -- has a wonderful aroma.'

...should, technically, be written with --- rather than -- . Should this be left as-is for consistency with the other text (which presumably uses --)? Or ,should I submit a pull request in which it has been corrected, thereby necessitating correction elsewhere, too?

Build issue: "File `todonotes.sty' not found."

When I make the project, the file todonotes.sty (included in Open-Advice.tex) is missing, and so the build fails.

I have tex, latex and pdflatex installed.

Dave.

its wireless --> it's wireless (page 240)

In page 240, the title reads

"It’ll work . . . its wireless!"

and should be

"It’ll work . . . it's wireless!"

Regards

website is needed

We need a website. Nigel is working on it.

todonotes required to build book

'''
$ pdflatex Open-Advice
This is pdfTeX, Version 3.1415926-1.40.10 (TeX Live 2009/Debian)
entering extended mode
(./Open-Advice.tex
LaTeX2e <2009/09/24>
Babel <v3.8l> and hyphenation patterns for english, usenglishmax, dumylang, noh
yphenation, loaded.
(/usr/share/texmf-texlive/tex/latex/memoir/memoir.cls
Document Class: memoir 2009/09/21 v1.61803398b configurable book, report, artic
le document class
(/usr/share/texmf-texlive/tex/generic/oberdiek/ifpdf.sty)
(/usr/share/texmf-texlive/tex/generic/ifxetex/ifxetex.sty)
(/usr/share/texmf-texlive/tex/generic/oberdiek/ifluatex.sty)
(/usr/share/texmf-texlive/tex/latex/etex-pkg/etex.sty)
(/usr/share/texmf-texlive/tex/latex/memoir/mem10.clo)
(/usr/share/texmf-texlive/tex/latex/memoir/mempatch.sty))
(/usr/share/texmf-texlive/tex/latex/base/inputenc.sty
(/usr/share/texmf-texlive/tex/latex/base/utf8.def
(/usr/share/texmf-texlive/tex/latex/base/t1enc.dfu)
(/usr/share/texmf-texlive/tex/latex/base/ot1enc.dfu)
(/usr/share/texmf-texlive/tex/latex/base/omsenc.dfu)))
(/usr/share/texmf-texlive/tex/latex/base/textcomp.sty
(/usr/share/texmf-texlive/tex/latex/base/ts1enc.def
(/usr/share/texmf-texlive/tex/latex/base/ts1enc.dfu)))
(/usr/share/texmf-texlive/tex/latex/graphics/graphicx.sty
(/usr/share/texmf-texlive/tex/latex/graphics/keyval.sty)
(/usr/share/texmf-texlive/tex/latex/graphics/graphics.sty
(/usr/share/texmf-texlive/tex/latex/graphics/trig.sty)
(/etc/texmf/tex/latex/config/graphics.cfg)
(/usr/share/texmf-texlive/tex/latex/pdftex-def/pdftex.def)))

! LaTeX Error: File `todonotes.sty' not found.
'''

"make us" should be "make use" (page 161)

In page 161, chapter 25 (online version)

"If the CD was not listed, you could enter the data so that the next person could make us of the data."

should be

"If the CD was not listed, you could enter the data so that the next person could make use of the data."

Regards

Assorted Typos - pages 57, 59, 61, 89

Page 57 - The Art of Problem Solving at the top of the page:
"addition, even if counter-intuitively, the act of describing the problem in its entirety often leads to finding of the solution, so much so that many development groups require “stuck” developers to perform this task, either by discussing it with a colleague or talking to a “naıve” entity, like a rubber duck or Mr. Potato-Head"

seems like it should read either "in its entirety often leads to the finding of the solution" or "in its entirety often leads to finding the solution"

Page 59 in the 1st full paragraph on that page -
"Verifying that the preconditions have been met is good exercise in the searching for an answer, for a violation of the preconditions is definitely a problem that needs solving – even if it is not the root cause of the original problem."

"is good exercise in the searching for an answer" should probably be "is good exercise searching for an answer" or "is a good exercise in the searching for an answer"

Page 61, 2nd paragraph, last sentence -
"That is an indication that the experience and behavior has set in so well that no conscious effort is required to access those skills"

I think has -> have in that case

Page 89 - Test Driven Enlightenment, 3rd paragraph, last sentence -
"Here is the how to approach adding a new feature or fixing a bug in any language:"

remove "the" before how

Page 258 Typo - Free Software in Public Administrations

In the first paragraph of page 258, it reads:

"Since disruptive change [it] difficult and expensive, it is far more important to have docu-mentation of the things that will not work, so they can be avoided or worked around, than it is to know that some future version will behave much better."

it should be is

Community Management - Jono Bacon (spelling/typo)

Spelling/typo in Community Management - Jono Bacon:

While each of
us has different belief systems, some map their belief systems to soft-
ware, some to education, some to knowledge, some to transparency
or whatever else, you ca not concoct a belief system unless it serves
a valid goal that a group are likely to care about.

Collection of Minor Corrections

p277, 2nd bullet -
"Legal certification and consulting: these companies do not pro-vide any specific code activity, but provide support in checking license compliance, sometimes also providing coverage and in-surance for legal attacks; some companies employ tools for [ver-ify] that code is not improperly reused across company bound-aries or in an improper way."
verify -> verifying

p278, top of the page -
"There is a large number of companies, universities and [individual] that participate in the Eclipse ecosystem."
individual -> individuals

p278, right before 2nd bullet -
"In the project, after an initial 1 year delay, the number of outside contribu-tions start to become significant, and after a little more than [1 and a half year] they surpass those performed by Apple by a substantial margin - thus reducing the maintenance costs and the engineering effort, thanks to the division of work among co-developers."
1 and a half year -> 1 and a half years

p280
RedHat -> Red Hat

p268
Redhat -> Red Hat

p276
RedHat -> Red Hat

p96, 4th paragraph
"The next day again in the cyber cafe, I read another of Eric S. Raymond’s [essay] called How To Ask Questions The Smart Way."
essay -> essays

same page, next sentence -
"I was still visiting the #hackers channel on Yahoo chat where I made a very good friend, Krish, who suggested [me to] buy a book called Linux Command Reference."
me to -> I

p97
"My blog has even simple postings like enabling the spell checker in OpenOffice [to] installing Django in a virtual environment."
to -> and
or
like -> from

to determined --> to determine (page 286)

In page 286, the last two lines:

" which helps to determined whether it is derived from another program or not."

should be

" which helps to determine whether it is derived from another program or not."

Proper E-Reader / Kindle Version

The PDF although it loads well will work better if a proper E-Reader / E-Pub / Kindle(mobi) version would be available for reading. Main issue with the PDF is that the letters are to small on a 6 or 7 inch reader.

Also a proper front cover would be nice!

Need a consistency passthrough for free software to Free Software and open source to Open Source

For the most part, it seems that people write about Open Source and some prefer to initial cap each word. Free software had less of a preference on my read throughs, so I left it as free software. I did change some open source to Open Source and need more work on consistency there.

essay titles and headings need consistent capitalization

All essay titles and the headings of the sections in them need to have consistent capitalization. Right now they're pretty random.

They team --> The team (page 211)

In page 211, after "...but because it was too ambitious."

"So why did it not work? They team did everything according to the best project management practices you will find on the web..."

should be

"So why did it not work? The team did everything according to the best project management practices you will find on the web..."

Regards

two bit.ly links do not work anymore

a.
Carlo Daffara: Free and Open Source-Based Business Models
page 280

http://bit.ly/7hHRB

leads to: http://ec.europa.eu/enterprise/ict/policy/doc/2006-11-20-flossimpact.pdf

working link:
http://ec.europa.eu/enterprise/sectors/ict/files/2006-11-20-flossimpact_en.pdf

b.
Selena Deckelmann: How to Ask for Money
page 247

http://bit.ly/woHCxf
new dir is:
https://github.com/osbridge/osbp_assets/blob/master/2011/2011%20Prospectus/2011%20Open%20Source%20Bridge%20Sponsorship%20Prospectus.pdf

info:
I did not correct with new bit.ly links since I assume you want to use your own bit.ly account
(P.S. I perceived the links as monitoring, though I assume it's used for shortening purpose)