Commit fda77fdb authored by Andreas Zwinkau's avatar Andreas Zwinkau
Browse files

revising tips

parent ead29cc6
......@@ -37,7 +37,7 @@ Manche Tipps und Tricks wiederholen wir häufig.
Dies ist eine Sammlung, um nichts zu vergessen
und weniger Fehler beim Erklären zu machen.
\section{Technisches}
\section{Tools für alle Phasen}
\dictum[Francis Glassborow]{
Good programmers use their brains,
......@@ -70,15 +70,16 @@ beim Erstellen einer pdf.
Diese sollten nicht im Versionskontrollsystem landen.
Ebensowenig die erzeugte pdf.
\subsection{Dokumentenformat}
Wer zusätzlich noch Github nutzt,
bekommt dort Issue Tracker, Code Review, und ähnliche Tools gleich dazu.
\subsection{Dokumentenformat: \LaTeX}
Wir empfehlen \LaTeX,
weil es sich gut mit Versionskontrollsystemen vereinbaren lässt
und man hier schon für die Bachelorarbeit üben kann.
Office o.ä. ist aber auch möglich.
\subsubsection{\LaTeX}
Statt den normalen Dokumentklassen,
empfiehlen wir vor allem für deutsche Dokumente
die KOMA-Scriptklassen zu verwenden.
......@@ -120,29 +121,45 @@ empfehlen wir einen Wrapper wie \texttt{latexmk} zu verwenden.
Dieser übernimmt beispielsweise das mehrfache Ausführen von \texttt{pdflatex},
wo es notwendig ist.
\subsection{GUI Entwürfe}
\section{Technisches Schreiben}
\dictum[Donald Knuth]{Anything that helps communication is good.
Anything that hurts is bad.
And that’s all I have to say.}
\begin{itemize}
\item \href{http://www.inkscape.org/de/}{Inkscape} ist ein freies Vektorzeichenprogramm
\item \href{http://pencil.evolus.vn/}{Pencil} ist ein Open-Source GUI Prototyping Tool (enthält Formen für Android, iOS, Web, GTK, Windows XP, Sketch, ...)
\item Die \href{http://developer.android.com/tools/index.html}{Android Developer Tools} enthalten einen grafischen UI Builder
\item Papier und Tusche geht natürlich auch
\end{itemize}
\subsection{UML Diagramme}
Technisches Schreiben ist wichtig für alle Arten von technischen und wissenschaftlichen Dokumenten,
also auch API-Dokumentation, Bachelorarbeit, Pflichtenheft und Testbericht.
Es bedeutet vor allem eine präzise Ausdrucksweise
und widerspricht dabei einigen Regeln,
die man im Deutschunterricht gelernt hat.
Ein paar praktische Tipps:
\begin{itemize}
\item \href{http://umbrello.kde.org/}{Umbrella} um einfach nur Diagramme zu zeichnen
\item \href{http://argouml.tigris.org/}{ArgoUML} um auch Code zu generieren und beim Entwurf zu helfen
\item \href{http://www-01.ibm.com/software/rational/uml/}{IBM Rational Software Architect} ist im ATIS Pool installiert.
\item \href{http://www.bouml.fr}{BOUML} noch ein UML Tool
\item \href{http://www.umlet.com/}{UMLet} noch ein UML Tool
\item \href{http://www.umlgraph.org/}{UMLGraph}
für Versions-Control-freundliche UML Diagramme.
\item \href{http://www.objectaid.com/}{ObjectAid UML Explorer for Eclipse}
ein Source-to-Diagram plugin.
\item Vermeide Adjektive.
Oft (nicht immer) sind sie unnötig oder
ein schlechter Ersatz für einen ungenauen Begriff.
\item Definiere Begriffe klar und verwende keine Synonyme.
Synonyme lassen offen, ob genau das gleiche gemeint ist
oder nur etwas ähnliches.
\item Abkürzungen sollten bei der ersten Verwendung (EV)
ausgeschrieben werden. Nach der EV reicht dann die Kurzform.
\item Versuche konkrete Zahlen und Namen anzugeben.
Vermeide ungenaue Ausflüchte wie:
meistens, viele, oft, möglichst, üblich, jemand, manche.
\item Viele kurze Sätze sind einfacher zu verstehen als wenige lange Sätze.
\item Beispiele machen das Endprodukt greifbarer.
\item Illustrationen minimalistisch halten (z.B. IKEA Bauanleitung).
Eine Information, ein Bild.
Lieber mehrere ähnliche Bilder als ein komplexes Bild.
\item Vermeide Wiederholung, stattdessen Referenzen benutzen.
Wiederholungen haben oft subtile Unterschiede,
was zu Unklarheit und Verwirrung führt.
Bei Änderungen wird oft vergessen,
dass Wiederholungen auch angepasst werden müssen.
\item Versionskontrolle ergibt auch für technische Texte Sinn
und nicht nur für Code.
\end{itemize}
\section{Kolloquium}
\dictum[Lilly Walters]{
......@@ -187,6 +204,7 @@ Design and programming are human activities; forget that and all is lost.
\item Mails an den Betreuer sollten vom Phasenverantwortlichen kommen.
\end{itemize}
\newpage
\section{Pflichtenheft}
\dictum[Dwight Eisenhower]{
......@@ -231,6 +249,9 @@ Und noch einige generelle Anforderungen an das Pflichtenheft.
zu großen Teilen verstanden werden können.
Am besten jemand fach-fremden zum Lesen geben
und danach Verständnisfragen stellen.
\item Das Pflichtenheft ist das entscheidenste Dokument
zwischen Kunde und Entwickler am Ende eines Projekts.
Es darf \textbf{keinen Spielraum für Interpretationen} offen lassen.
\item Erfahrungsgemäßer Umfang: ca. 40 Seiten
\end{itemize}
......@@ -256,45 +277,15 @@ Sinnvolle Änderungen könnten sein:
und die erwartet Reaktion des Programms sein.
\end{itemize}
\subsection{Technisches Schreiben}
Technisches Schreiben ist wichtig für alle Arten von technischen und wissenschaftlichen Dokumenten,
also auch API-Dokumentation, Bachelorarbeit und Pflichtenheft.
Es bedeutet vor allem eine präzise Ausdrucksweise
und widerspricht dabei einigen Regeln,
die man im Deutschunterricht gelernt hat.
Ein paar praktische Tipps:
\subsection{GUI Entwürfe}
\begin{itemize}
\item Vermeide Adjektive.
Oft (nicht immer) sind sie unnötig oder
ein schlechter Ersatz für einen ungenauen Begriff.
\item Definiere Begriffe klar und verwende keine Synonyme.
Synonyme lassen offen, ob genau das gleiche gemeint ist
oder nur etwas ähnliches.
\item Abkürzungen sollten bei der ersten Verwendung (EV)
ausgeschrieben werden. Nach der EV reicht dann die Kurzform.
\item Versuche konkrete Zahlen und Namen anzugeben.
Vermeide ungenaue Ausflüchte wie:
meistens, viele, oft, möglichst, üblich, jemand, manche.
\item Viele kurze Sätze sind einfacher zu verstehen als wenige lange Sätze.
\item Beispiele machen das Endprodukt greifbarer.
\item Illustrationen minimalistisch halten (z.B. IKEA Bauanleitung).
Eine Information, ein Bild.
Lieber mehrere ähnliche Bilder als ein komplexes Bild.
\item Vermeide Wiederholung, stattdessen Referenzen benutzen.
Wiederholungen haben oft subtile Unterschiede,
was zu Unklarheit und Verwirrung führt.
Bei Änderungen wird oft vergessen,
dass Wiederholungen auch angepasst werden müssen.
\item Versionskontrolle ergibt auch für technische Texte Sinn
und nicht nur für Code.
\item \href{http://www.inkscape.org/de/}{Inkscape} ist ein freies Vektorzeichenprogramm
\item \href{http://pencil.evolus.vn/}{Pencil} ist ein Open-Source GUI Prototyping Tool (enthält Formen für Android, iOS, Web, GTK, Windows XP, Sketch, ...)
\item Die \href{http://developer.android.com/tools/index.html}{Android Developer Tools} enthalten einen grafischen UI Builder
\item Papier und Tusche geht natürlich auch
\end{itemize}
Das Pflichtenheft ist das entscheidenste Dokument
zwischen Kunde und Entwickler am Ende eines Projekts.
Es darf \textbf{keinen Spielraum für Interpretationen} offen lassen.
\subsection{Inhalt der Präsentation}
\begin{itemize}
......@@ -304,6 +295,7 @@ Es darf \textbf{keinen Spielraum für Interpretationen} offen lassen.
\item Ein Testfallszenario als anschauliches durchgehenden Beispiel
\end{itemize}
\newpage
\section{Entwurf}
\dictum[Bob Martin]{
......@@ -392,6 +384,20 @@ Paradoxe Anforderungen zeigen, dass gutes Design ein Kunst ist.
ohne das Kontext notwendig ist.
\end{itemize}
\subsection{UML Diagramme}
\begin{itemize}
\item \href{http://umbrello.kde.org/}{Umbrella} um einfach nur Diagramme zu zeichnen
\item \href{http://argouml.tigris.org/}{ArgoUML} um auch Code zu generieren und beim Entwurf zu helfen
\item \href{http://www-01.ibm.com/software/rational/uml/}{IBM Rational Software Architect} ist im ATIS Pool installiert.
\item \href{http://www.bouml.fr}{BOUML} noch ein UML Tool
\item \href{http://www.umlet.com/}{UMLet} noch ein UML Tool
\item \href{http://www.umlgraph.org/}{UMLGraph}
für Versions-Control-freundliche UML Diagramme.
\item \href{http://www.objectaid.com/}{ObjectAid UML Explorer for Eclipse}
ein Source-to-Diagram plugin.
\end{itemize}
\subsection{Mehr Links}
\begin{itemize}
......@@ -421,15 +427,16 @@ Paradoxe Anforderungen zeigen, dass gutes Design ein Kunst ist.
und Dialoge.
\end{itemize}
\newpage
\section{Implementierung}
\dictum[Linus Torvalds]{Talk is cheap. Show me the code.}
\artefakt{Implementierungsplan zu Beginn,
Implementierungsbericht
und vollständiger source code}
Implementierungsbericht als PDF Dokument
und vollständiger Source Code}
\subsection{Implementierungsplan}
\subsection{Plan}
\begin{itemize}
\item Klarer zeitlicher Ablauf der Implementierungsphase,
......@@ -442,7 +449,7 @@ Paradoxe Anforderungen zeigen, dass gutes Design ein Kunst ist.
beim Betreuer abzugeben.
\end{itemize}
\subsection{Implementierungsbericht}
\subsection{Bericht}
\begin{itemize}
\item Erfahrungsgemäßer Umfang: ca. 20 Seiten
......@@ -540,9 +547,10 @@ Label Alice Bob Carol Dan Eve
\label{fig:loc-per-person}
\caption{Anzahl Codezeilen je Person über 5 Wochen hinweg.
Diese Art von Graph zeigt dass die Verteilung im Team fair aussieht.
Auch sieht man den kontinuierlichen Wachstum.}
Man sieht auch das kontinuierliche Wachstum.}
\end{figure}
\newpage
\section{Qualitätssicherung}
\dictum[Edsger Dijkstra]{
......@@ -550,7 +558,7 @@ Program testing can be used to show the presence of bugs,
but never to show their absence!
}
\artefakt{Testberichte}
\artefakt{Testbericht}
\begin{itemize}
\item Überdeckung der Unittests maximieren.
......@@ -561,7 +569,7 @@ but never to show their absence!
Ein Testdurchlauf sollte möglichst automatisch ablaufen.
\item \href{http://developer.android.com/tools/help/monkeyrunner_concepts.html}{Monkey Testing}
für einfaches GUI testen.
Der Ertrag ist vermutlich nicht sehr groß,
Der Ertrag ist erfahrungsgemäß nicht sehr groß,
also nicht zuviel Aufwand hineinstecken.
Automatisierung mit
......@@ -578,6 +586,7 @@ but never to show their absence!
Ergebnisse dokumentieren.
\item Alle gefunden Bugs und deren Reparatur dokumentieren.
So entsteht der Testbericht am Ende.
Schema im Bericht: Fehlersymptom, -grund und -behebung
\end{itemize}
\newpage
......@@ -612,6 +621,8 @@ Nebenbei dürfen folgende Informationen auch in den Vortrag:
Mindestens sollten alle Namen auf den Folien stehen.
Alle Teammitglieder sollten sich mal zeigen.
Vielleicht können sogar alle sinnvoll in die Präsentation eingebunden werden?
\item Welche Tools hab ihr für die verschiedenen Aufgaben benutzt
und wie gut fandet ihr sie?
\end{itemize}
Zu diesem Zeitpunkt habt ihr erfolgreich ein ordentliches Softwareprojekt
......@@ -647,4 +658,12 @@ Zum Beispiel könnt ihr die folgenden beiden Fragen beantworten:
\item Warum in Frage 1 genau diese Zahl?
\end{enumerate}
\vfill
\begin{center}
when you don't create things, you become defined by your tastes rather than ability.
your tastes only narrow \& exclude people. so \textbf{create}.
\hfill --- Why The Lucky Stiff
\end{center}
\end{document}
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment