% !TeX encoding = UTF-8
% !TeX spellcheck = en_US
% !TeX root = WSP.tex



\section{Build the reference database}
% Read... an build the bibliographic data base
% BibTeX
%{BaTiO3}
%
\subsection{Read, share and remember}
\begin{frame}{Read before you write}{Be sure to stand on the shoulders of the giant}
	\begin{Boite}{Literature review\hfill Scientific \& technological intelligence}
		\begin{itemize}
			\item Scientific writing is always about a first-time-ever
			\item<2-|alert@2> Read related work
			\item<3-> \alert<3>{Record} related work
			\item<4-> Get your scientific intelligence \alert<4>{organized}
			\item<5-> Get help from a \only<6-|handout:1>{\alert<6>{community }}\alert<5>{reference manager}
		\end{itemize}
	\end{Boite}
\uncover<5->{
	\begin{Boite}{Reference managers\hfill\only<5-|handout:1>{My favorites}}
		\begin{itemize}
			\item \url{https://en.wikipedia.org/wiki/Comparison_of_reference_management_software}
			\item<5-> For yourself: \JabRef
			\item<6-> Community work: \Zotero
			\begin{itemize}
				\item<7-> \href{https://bu.univ-lorraine.fr/formations/formations-doctorants-chercheurs}{Domptez la Doc}
			\end{itemize}
		\end{itemize}
	\end{Boite}
}
\end{frame}


\subsection{The \BibTeX tool}

\begin{frame}{Efficiently recording relevant literature for further reference}{\BibTeX: a reference management software and a raw text file format}

\begin{Boite}{\BibTeX: manage your reference and get them cited in \LaTeX}
	\begin{itemize}
		\item Store your references in one, or several, \dotbib files
		\item<2-> Cite a reference as you write \hfill \texttt{\textbackslash cite(\alert{ref-key})}
		\item<3-> Get the references automatically filled in with the layout of your choice
	\end{itemize}
\end{Boite}
\end{frame}

\begin{frame}[fragile]{The \BibTeX file format}{A raw text file for all your bibliographic data}
	\begin{Boite}{A sample \BibTeX item}
%\only<1|handout:0>{
\begin{lstlisting}
@article{ECARNOT2015573,
title = "Writing a scientific article: A step-by-step guide for beginners",
journal = "European Geriatric Medicine",
volume = "6",
number = "6",
pages = "573 - 579",
year = "2015",
issn = "1878-7649",
doi = "https://doi.org/10.1016/j.eurger.2015.08.005",
url = "http://www.sciencedirect.com/science/article/pii/S1878764915001606",
author = "F. Ecarnot and M.-F. Seronde and R. Chopard and F. Schiele and N. Meneveau",
keywords = "Scientific publications, Writing, Research, Article"
}\end{lstlisting}
\end{Boite}
\uncover<2->{
\begin{Boite}{Tune the elements you need}
	\begin{itemize}
		\item \texttt{@article}, \texttt{@book}, \texttt{@inproceedings}, \texttt{@phdthesis}\dots
		\item<3-> \alert{ECARNOT2015573}: an arbitrary key
		\item<4-> Self-explanatory fields, some required, others optional
	\end{itemize}
\end{Boite}
}
\end{frame}

\subsection{Practice time}

\begin{frame}{Build a \dotbib database of your own}{\dotbib hand editing or using \JabRef or \Zotero}
	\begin{Boite}{\dotbib hand editing}
		\begin{itemize}
		\item Use your favorite raw text editor to manually fill in your \dotbib file.		
		\item Use references of your own or from a Wikipedia article
		\item<alert@1> {A \LaTeX\  designed raw text editor\footnote{TexStudio, Kile, TeXShop, TeXMaker, WinEdt,TeXnicCenter\dots} can help fill \dotbib file}
		\end{itemize}
	\end{Boite}
	\uncover<2->{
	\begin{Boite}{\dotbib assisted editing}
		\begin{itemize}
			\item Use \JabRef and/or \Zotero and/or a reference manager of your choice to build a bibliographic database\footnote{Use references of your own or from a Wikipedia article}		
			\item Export a \dotbib \BibTeX file
		\end{itemize}
	\end{Boite}
	}
\end{frame}

\section{Design the article}
\subsection{Successive approximations writing}

\begin{frame}{Actual paper writing}{OK\dots Research background read and recorded\dots Research itself ready for writing\dots}
\begin{BoiteEmphCentre}{DO NOT start by the beginning}
It is \alert{REALLY difficult} to start writing an article without knowing the end
\end{BoiteEmphCentre}
\pause
\begin{BoiteEmphCentre}{DO NOT start by the end}
	It is \alert{REALLY difficult} to imagine the end of an article without having written the beginning
\end{BoiteEmphCentre}
\pause
\begin{BoiteCentre}{Imagine a way to write all the  article as a whole}
	\href{https://www.sindark.com/2017/03/14/writing-as-successive-approximation/}{Successive approximation writing}
\end{BoiteCentre}
\end{frame}


\newcommand{\subpart}{\only<2-|handout:1>{
\begin{itemize}
	\item part \only<3-|handout:0>{
		\begin{itemize}
			\item part
			\item part
			\item part
		\end{itemize}
	}
	\item part\only<3-|handout:0>{
		\begin{itemize}
			\item part
			\item part
			\item part
		\end{itemize}
	}
	\item part\only<3-|handout:0>{
		\begin{itemize}
			\item part
			\item part
			\item part
		\end{itemize}
	}
\end{itemize}
}}

\begin{frame}{Successive approximations writing}{Writing the paper as a whole to keep constistency throughout the writing process}
\begin{columns}
	\begin{Column}
	\begin{Boite}{A paper being written}
		\only<2|handout:1>{\scriptsize}
		\only<3|handout:0>{\tiny}
	\begin{itemize}
		\item Introduction
		\item Part I \subpart
		\item Part II \only<1-2>{\subpart}
		\only<1-2>{\item Part III \subpart
		\item end matter}
	\end{itemize}
	\end{Boite}	
	\end{Column}
	\begin{Column}
		\begin{BoiteCentre}{A simple algorithm}
			\includegraphics[width=\linewidth]{SAW}
		\end{BoiteCentre}
	\end{Column}
\end{columns}
\end{frame}



\subsection[Tables \& Figures]{Self-consistent figures and table}
% Insert the tables and figures
% Keep the captions self-consistent
%

\begin{frame}{Figures and tables are really important}{The hasty reader reads: title, abstract, author list, figures, references, conclusion\dots \hfill and sometimes the paper}

\begin{Boite}{Successful production of good figures requires substantial effort}
	\begin{itemize}
		\item Use \href{https://en.wikipedia.org/wiki/Vector\_graphics}{vector graphics}\footnote{Vector graphics: PDF, EPS, SVG\dots} for infinite resolution and small file size
		\item<2-> Insure good resolution for pictures
		\item<3-> Keep it clear and simple
		\item<4-> Insure black  \& white readability
		\item<5-> My favorites to create figures: \href{https://matplotlib.org/}{\texttt{Python} \& \texttt{matplotlib}}, \href{http://www.sagemath.org/}{\texttt{SageMath} and \href{https://inkscape.org/}{\texttt{inkscape}}}
	\end{itemize}
\end{Boite}
\uncover<6->{
\begin{BoiteEmphCentre}{Self-consistent figures, tables and captions}
%	\begin{itemize}
		A paper should be understandable through the figures, tables, and their captions 
%	\end{itemize}
\end{BoiteEmphCentre}
}
\end{frame}

%\begin{frame}{Figures and tables should be self consistent}{A paper should be understandable through the figures and their captions}
%	\begin{Boite}{Figure and table captions should\dots}
%		\begin{itemize}
%			\item thoroughly describe the figure,
%			\item make the figure independent of the paper text,
%			\item not hesitate to repeat the paper text.
%		\end{itemize}
%	\end{Boite}
%\end{frame}

\begin{frame}[fragile]{\LaTeX\  how-to for figures and tables}{Be sure to use PDF\LaTeX, otherwise, only EPS file format is allowed}
\begin{Boite}{Include the \alert{graphics} package}
	\begin{lstlisting}
	\documentclass{article}
	%
	\usepackage{graphicx} % graphicx is the modern version of graphics
	%
	\begin{document}
	\end{lstlisting}
\end{Boite}
%
\pause
%\uncover<2->{
\begin{Boite}{Create a figure file}
	\begin{itemize}
		\item Preferably a vector PDF graphics file
		\item PNG for bitmap graphics, JPG for pictures
	\end{itemize}
\end{Boite}
%}
%
\pause
%\begin{colmuns}
%	\begin{Column}
	\begin{Boite}{Declare the figure at the right place}
\begin{lstlisting}
\begin{figure}
\centering
\includegraphics{Tux.png}
\caption{Tux, le pingouin}
\label{Tux}
\end{figure}
\end{lstlisting}
	\end{Boite}
%	\end{Column}
%\end{columns}
%\uncover<3->{

%}
%
\end{frame}

\begin{frame}{Inserting figure at the right place}{Let \LaTeX place the figures nicely, it knows what its doing}
	\begin{Boite}{Editing rules for figures and tables}
		\begin{itemize}
			\item Figure as close as possible to its declaration
			\item Figure \alert{never} before its declaration
			\item Figure does not break text
			\item Figure preferably on page top, bottom if possible, on page if necessary
			\item If text is present on page a minimum fraction of the page is required
		\end{itemize}
	\end{Boite}
	\pause
	\begin{BoiteEmphCentre}{Let \LaTeX place the figure}
		Declare the figure just before the paragraph where it is referred first
	\end{BoiteEmphCentre}
\end{frame}

\begin{frame}{Figure and table reference}{Automated numbering of figures and tables for an atomatic referencing}
	\begin{Boite}{The \texttt{\textbackslash label} command}
		\begin{itemize}
			\item \texttt{\textbackslash label\{AnyKeyYouWant\}}
			\item For figures, table, equations, sections...
			\item Allows automated referencing to the object it is in
		\end{itemize}
	\end{Boite}
	\pause
	\begin{Boite}{The \texttt{\textbackslash ref} command}
		\begin{itemize}
			\item The \texttt{\textbackslash ref\{AnyKeyYouWant\}} command is replaced by the referenced object number
		\end{itemize}
	\end{Boite}
	\uncover<3->{
	\begin{Boite}{The \texttt{varioref} package}
		\begin{itemize}
			\item Numerous figures can be rejected far from their reference
			\item In a long document, figures can lie many pages before  \texttt{\textbackslash ref}
			\item<4-> \texttt{varioref} is the solution: it includes the page number along with the figure number
		\end{itemize}
	\end{Boite}
	}
\end{frame}


\begin{frame}[fragile]{As you write and cite, the reference list builds up}{\BibTeX and \LaTeX\  magic}
	\begin{Boite}{Place at the end of your paper}
		\begin{lstlisting}
		\bibliographystyle{unsrt} % or any other relevant style
		\bibliography{bibfile1,bibfile2,bibfile3...}
		\end{lstlisting}
	\end{Boite}
\end{frame}

\subsection{Practice time}

\begin{frame}{Build the skeleton of your first scientific paper}{Ultra detailed outline, figures and automatic citations}
	\begin{Boite}{Get ready for writing}
		\begin{itemize}
			\item Design your paper skeleton using successive approximation writing	
			\item Carefully design self consistent figures and tables
			\item Declare them in your paper skeleton\footnote{Don't worry, \LaTeX will stack them et the end of the paper, but this will change as text is added}
			\item Link your bibliography database
		\end{itemize}
	\end{Boite}
\end{frame}


\section{Write the article}
% Remember the basic aim: reproducible research. The reader should be able to do it again
% Define everything
% Keep it concise !!
%
\subsection{Usual Layout}
\begin{frame}{Introduction}{Decribes the time and space context of the work to make the paper readable as a whole}
	\begin{Boite}{Introduction probably includes}
		\begin{itemize}
			\item The paper specific domain
			\item A description of the problem tackled
			\item A review of the past attempts to tackle the same problem
			\begin{itemize}
				\item Lots of references here
			\end{itemize}
			\item A description of the novelties your work proposes
			\item A review of the article organization and strategy to present the work done
			\begin{itemize}
				\item<2-> Materials, methods, experiments\dots
				\item<2-> Results
				\item<2-> Discussion
			\end{itemize}
		\end{itemize}
	\end{Boite}
\end{frame}


\begin{frame}{Materials, methods, experiments\dots}{Describes the methods used so that the work can be \emph{reproducible}}
\begin{Boite}{First goal: convince that your methods are scientifically sound}
	\begin{itemize}
		\item Be sure to give all the details
		\item Include experimental framework and detailed conditions
		\item Include data collection and analysis
		\item Justify all, either directly of through references
	\end{itemize}
\end{Boite}
\pause
\begin{Boite}{Second goal: make your work \emph{reproducible}}
	\begin{itemize}
	\item Be sure to give all the details
	\item Open the methods as much as you can:
	\begin{itemize}
		\item Measurement apparatus model, reference, \emph{and inner details}
		\item Open source software, or precisely referenced software
		\item Detailed experimental sketches
		\item \dots
	\end{itemize}
	\end{itemize}
\end{Boite}
\end{frame}


\begin{frame}{Results}{Results, only results: give the reader a chance  interpret them on his/her own}
\begin{Boite}{Give raw results in a human understandable manner}
	\begin{itemize}
		\item Small tables
		\begin{itemize}
			\item Avoid huge tables
		\end{itemize}
		\item 2D curves
		\begin{itemize}
			\item Think twice before going 3D
			\item If approximations or interpolations are done, tell why and how
		\end{itemize}
	\end{itemize}
\end{Boite}
\pause
\begin{Boite}{Consider publishing your data in data warehouses}
	\begin{itemize}
	\item Allows the reader to get the numbers
	\item Insure a long life to your data
	\item Allow others to browse your data
	\item Certify your data is sound and honest
	\item Allow Google and other to index your data
	\item Produce a DOI for your CV
	\end{itemize}
\end{Boite}

\end{frame}
\begin{frame}{Discussion}{The only section which can go away from raw facts}
	\begin{Boite}{Finally, you can write about what you are thinking}
		Potential advices:
		\begin{itemize}
			\item summarize your problem,
			\item clarify your hypotheses\dots
			\item<2-|alert@2> and finally write about what you refrained to say from the very beginning.
		\end{itemize}   
	\end{Boite}
	
\end{frame}
\subsection{A specific writing style}

\begin{frame}{Scientific writing style}{Be clear and concise}
	\begin{Boite}{Be clear}
		\begin{itemize}
			\item Define \alert{everything}: math variables, acronyms\dots
			\item One word has one specific meaning: chose carefully
			\item Avoid \emph{and so on}, \emph{etc.}\dots
		\end{itemize}
	\end{Boite}
	\pause
	\begin{Boite}{Be concise}
		\begin{itemize}
			\item Do not say anything twice,
			\begin{itemize}
				\item unless you have a good reason.
			\end{itemize}
			\item Avoid literature style effects,
			\begin{itemize}
				\item except if it allows even more conciseness.
			\end{itemize}
		\end{itemize}
	\end{Boite}
	\pause
	\begin{BoiteEmph}{Avoid}
		\begin{itemize}
			\item trying to impress the reader,
			\item using abbreviations ("does not" instead of "doesn't").
		\end{itemize}
	\end{BoiteEmph}
\end{frame}

\begin{frame}{Final note on plagiarism and referencing}{About using the work of authors, or the shoulders of giants}
	\begin{BoiteEmph}{Using the work of authors is good, and necessary}
		\begin{itemize}
			\item Be sure to completely understand the cited work
			\item Properly reference the previous writings
			\item Even properly referenced figures can be reused, if their license\footnote{Present licenses tend to go towards the CC-BY Creative Commons Attributions licence} allows so
			\item If absolutely necessary, the words of others can also be used, between quotes and properly attributed
		\end{itemize}
	\end{BoiteEmph}
\end{frame}
\begin{frame}{Advanced team working}{Writing a paper is usually a team work. \texttt{git} is the ultimate solution }
	\begin{Boite}{Using git for collaborative \LaTeX}
		\begin{itemize}
			\item Use \texttt{gitlab} on \url{https://framagit.org}
			\item \url{https://youtu.be/YprjPIMtFnk}
			\item \url{https://www.google.com/search?q=git+latex}
			\item \url{https://twitter.com/Blogozoic/status/954089174461755392}
		\end{itemize}

	\end{Boite}

\end{frame}
