...
 
Commits (3)
digraph abc {
rankdir=LR;
a -> b -> c;
}
%docker in action
@book{alma9946882736704105,
author = "Nickoloff, Jeff",
address = "Shelter Island, NY",
booktitle = "Docker in Action",
isbn = "1-63343-023-5",
keywords = "Application software -- Development -- Automation",
language = "eng",
publisher = "Manning Publications",
title = "Docker in Action",
year = "2016",
ANNOTATE = "Mr. Nickoloff has been a Software Engineer working in web-development for 20 years. This book covers Docker, a containerization tool that lies at the root of the DevOps revolution. This book is a tutorial on Docker.",
}
%fix the case
%a) evaluate authors
%b)summarize scope and purpose of paper
%c)summarize central idea or findings
%d) compare to other works
%docker
@misc{docker,
title={Docker Documentation},
url={https://docs.docker.com/},
journal={Docker Documentation},
year={2019},
month=5,
type={\bibcomputerprogrammanual},
ANNOTATE="Docker is the world leader in containerization software. Docker is the building block of DevOps. This resource is the authoritative reference on Docker, where as Docker In Action is written to be user-friendly.",
}
%unified devops
@INPROCEEDINGS{7339039,
author={A. {Wahaballa} and O. {Wahballa} and M. {Abdellatief} and H. {Xiong} and Z. {Qin}},
booktitle={2015 6th IEEE International Conference on Software Engineering and Service Science (ICSESS)},
title={Toward Unified DevOps Model},
year={2015},
volume={},
number={},
pages={211-214},
keywords={DP industry;software engineering;standardisation;unified DevOps model;DevOps community;software deployment;UDOM model;workflow execution model;standardization;Software;Data models;Testing;Organizations;Collaboration;Terminology;Industries;DevOps;conceptual deficit;Unified DevOps Model (UDOM)},
doi={10.1109/ICSESS.2015.7339039},
ISSN={2327-0594},
month=9,
ANNOTATE="A. Wahballa is a post doctorate fellow at the University of Electronic Science and Technology of China;s School of Information and Software Engineering. He, like O. Wahballa has a handful of publications on IEEE. This paper can help Clarify confusions companies have when working with a specific vendor's DevOps product as they'll already have a framework for understand DevOps. This paper will help build models.",}
%DevOps and Microservices
@INPROCEEDINGS{8312518,
author={M. {Waseem} and P. {Liang}},
booktitle={2017 24th Asia-Pacific Software Engineering Conference Workshops (APSECW)},
title={Microservices Architecture in DevOps},
year={2017},
pages={13-14},
keywords={software architecture;software development management;software maintenance;software prototyping;DevOps;microservices architecture;MSA;software engineering paradigms;Systematics;Computer architecture;Software engineering;Conferences;Architecture;Market research;Microservices Architecture;DevOps;Systematic Mapping Study},
doi={10.1109/APSECW.2017.18},
month=12,
ANNOTATE={P. Liang has 25 papers many related to DevOps and programmer collaboration. M.Waseem is relatively unpublished. Microservices is used in DevOps to limit the scope of a component of an IT archetecture. This enables collaboration and DevOps.},
}
%GitLab
@misc{gitlab,
title={Introduction to CI/CD with GitLab},
url={https://docs.gitlab.com/ee/ci/introduction/},
journal={GitLab},
ANNOTATE="GitLab is one of many DevOps-enabled software development products, but it is the best one, so I'll discuss it in the paper. Like the docker resource above, this website is mostly technical documentation so pulling from it may be hard.",
publisher={GitLab},
}
%devops cambrian explosion
@ARTICLE{8314153,
author={M. {Kersten}},
journal={IEEE Software},
title={A Cambrian Explosion of DevOps Tools},
year={2018},
volume={35},
number={2},
pages={14-17},
keywords={project management;software development management;resulting tool diversity;modern DevOps toolchain;Cambrian Explosion;value stream architecture;Software tools;Software development management;Task analysis;agile software development;DevOps;DevOps tools;value stream architecture;software development;software engineering},
doi={10.1109/MS.2018.1661330},
ISSN={0740-7459},
month=3,
ANNOTATE="Dr. Kersten is the Founder and CEO of Tasktop, he's been a PhD in Computer Science nearly 20 years ago now. This resource shows how new DevOps is, which shows why documentation is used."}
%documentation source
@inproceedings{Dagenais:2010:CED:1882291.1882312,
author = "Dagenais, Barth'el'emy and Robillard, Martin P.",
title = "Creating and Evolving Developer Documentation: Understanding the Decisions of Open Source Contributors",
booktitle = "Proceedings of the Eighteenth ACM SIGSOFT International Symposium on Foundations of Software Engineering",
series = "FSE '10",
year = 2010,
isbn = "978-1-60558-791-2",
location = "Santa Fe, New Mexico, USA",
pages = {127--136},
numpages = 10,
url = "http://doi.acm.org/10.1145/1882291.1882312",
doi = "10.1145/1882291.1882312",
acmid = 1882312,
publisher = "ACM",
address = "New York, NY, USA",
keywords = "developer documentation; framework; grounded theory; open source projects; qualitative studies; software documentation",
ANNOTATE="The authors of this paper are extremely prolific (Dagenais with 16 other papers on ACM and Robillard with 78). This resource informs the discussion on the importance of documentation and how to write good documentation.",
}
\ No newline at end of file
% !TeX root = ./finalPaperDraft.tex
\documentclass[titlepage]{article}
\author{Michael Lundquist}
\title{Multiprocessor programming}
%-----------begin-preamble---------------------------
\usepackage{a4wide} %wide use of a4 paper
\usepackage{apacite} %bibliography in apa-style
\usepackage[doublespacing]{setspace}
\begin{document}
\maketitle
%====================================================
%-----------------references-------------------------
%====================================================
\bibliographystyle{apacann} %this was the key
\setlength{\bibleftmargin}{.125in}
%\setlength{\bibindent}{-\bibleftmargin}
\doublespacing
\bibliography{finalPaperDraft}
%\bibindent
%\bibleftmargin
\nocite{*}
\end{document}
\ No newline at end of file
digraph abc {
rankdir=LR;
a -> b -> c;
}
%docker in action
@book{alma9946882736704105,
author = "Nickoloff, Jeff",
address = "Shelter Island, NY",
booktitle = "Docker in Action",
isbn = "1-63343-023-5",
keywords = "Application software -- Development -- Automation",
language = "eng",
publisher = "Manning Publications",
title = "Docker in Action",
year = "2016",
ANNOTATE = "Mr. Nickoloff has been a Software Engineer working in web-development for 20 years. This book covers Docker, a containerization tool that lies at the root of the DevOps revolution. This book is a tutorial on Docker.",
}
%fix the case
%a) evaluate authors
%b)summarize scope and purpose of paper
%c)summarize central idea or findings
%d) compare to other works
%docker
@misc{docker,
title={Docker Documentation},
url={https://docs.docker.com/},
journal={Docker Documentation},
year={2019},
month=5,
type={\bibcomputerprogrammanual},
ANNOTATE="Docker is the world leader in containerization software. Docker is the building block of DevOps. This resource is the authoritative reference on Docker, where as Docker In Action is written to be user-friendly.",
}
%unified devops
@INPROCEEDINGS{7339039,
author={A. {Wahaballa} and O. {Wahballa} and M. {Abdellatief} and H. {Xiong} and Z. {Qin}},
booktitle={2015 6th IEEE International Conference on Software Engineering and Service Science (ICSESS)},
title={Toward Unified DevOps Model},
year={2015},
volume={},
number={},
pages={211-214},
keywords={DP industry;software engineering;standardisation;unified DevOps model;DevOps community;software deployment;UDOM model;workflow execution model;standardization;Software;Data models;Testing;Organizations;Collaboration;Terminology;Industries;DevOps;conceptual deficit;Unified DevOps Model (UDOM)},
doi={10.1109/ICSESS.2015.7339039},
ISSN={2327-0594},
month=9,
ANNOTATE="A. Wahballa is a post doctorate fellow at the University of Electronic Science and Technology of China;s School of Information and Software Engineering. He, like O. Wahballa has a handful of publications on IEEE. This paper can help Clarify confusions companies have when working with a specific vendor's DevOps product as they'll already have a framework for understand DevOps. This paper will help build models.",
}
%DevOps and Microservices
@INPROCEEDINGS{8312518,
author={M. {Waseem} and P. {Liang}},
booktitle={2017 24th Asia-Pacific Software Engineering Conference Workshops (APSECW)},
title={Microservices Architecture in DevOps},
year={2017},
pages={13-14},
keywords={software architecture;software development management;software maintenance;software prototyping;DevOps;microservices architecture;MSA;software engineering paradigms;Systematics;Computer architecture;Software engineering;Conferences;Architecture;Market research;Microservices Architecture;DevOps;Systematic Mapping Study},
doi={10.1109/APSECW.2017.18},
month=12,
ANNOTATE={P. Liang has 25 papers many related to DevOps and programmer collaboration. M.Waseem is relatively unpublished. Microservices is used in DevOps to limit the scope of a component of an IT archetecture. This enables collaboration and DevOps.},
}
%GitLab
@misc{gitlab,
title={Introduction to CI/CD with GitLab},
url={https://docs.gitlab.com/ee/ci/introduction/},
journal={GitLab},
ANNOTATE="GitLab is one of many DevOps-enabled software development products, but it is the best one, so I'll discuss it in the paper. Like the docker resource above, this website is mostly technical documentation so pulling from it may be hard.",
publisher={GitLab},
}
%devops cambrian explosion
@ARTICLE{8314153,
author={M. {Kersten}},
journal={IEEE Software},
title={A Cambrian Explosion of DevOps Tools},
year={2018},
volume={35},
number={2},
pages={14-17},
keywords={project management;software development management;resulting tool diversity;modern DevOps toolchain;Cambrian Explosion;value stream architecture;Software tools;Software development management;Task analysis;agile software development;DevOps;DevOps tools;value stream architecture;software development;software engineering},
doi={10.1109/MS.2018.1661330},
ISSN={0740-7459},
month=3,
ANNOTATE="Dr. Kersten is the Founder and CEO of Tasktop, he's been a PhD in Computer Science nearly 20 years ago now. This resource shows how new DevOps is, which shows why documentation is used."}
%documentation source
@inproceedings{Dagenais:2010:CED:1882291.1882312,
author = "Dagenais, Barth'el'emy and Robillard, Martin P.",
title = "Creating and Evolving Developer Documentation: Understanding the Decisions of Open Source Contributors",
booktitle = "Proceedings of the Eighteenth ACM SIGSOFT International Symposium on Foundations of Software Engineering",
series = "FSE '10",
year = 2010,
isbn = "978-1-60558-791-2",
location = "Santa Fe, New Mexico, USA",
pages = {127--136},
numpages = 10,
url = "http://doi.acm.org/10.1145/1882291.1882312",
doi = "10.1145/1882291.1882312",
acmid = 1882312,
publisher = "ACM",
address = "New York, NY, USA",
keywords = "developer documentation; framework; grounded theory; open source projects; qualitative studies; software documentation",
ANNOTATE="The authors of this paper are extremely prolific (Dagenais with 16 other papers on ACM and Robillard with 78). This resource informs the discussion on the importance of documentation and how to write good documentation.",
}
\ No newline at end of file
......@@ -20,19 +20,19 @@
%\setlength{\bibindent}{-\bibleftmargin}
\doublespacing
In “Creating and Evolving Developer Documentation: Understanding the Decisions of Open Source Contributions” Barthélémy Dagenais and Martin P. Robillard discuss the aspects of effective documentation. Using historical analysis and interviews, the authors determined how documentation is written and best practices for writing documentation. The historical analysis was primarily used to determine how documentation is currently written. Interviews were primarily used to determine pros and cons of different types of documentation. Although documentation methods differ for different types of projects, all projects benefit from good documentation in similar ways. Documentation can be a huge competitive advantage for a project. According to one of the interviewed contributors, "even if his project launched a year after a competing project, the user base grew quickly because the competing project had no documentation." \cite[p.6]{Dagenais:2010:CED:1882291.1882312}
In “Creating and Evolving Developer Documentation: Understanding the Decisions of Open Source Contributions” Barthélémy Dagenais and Martin P. Robillard discuss the aspects of effective documentation. Using historical analysis and interviews, the authors determined how documentation is written and best practices for writing documentation. The historical analysis was primarily used to determine how documentation is currently written. Interviews were primarily used to determine pros and cons of different types of documentation. Although documentation methods differ for different types of projects, all projects benefit from good documentation in similar ways. Documentation can be a huge competitive advantage for a project. According to one of the interviewed contributors," even if his project launched a year after a competing project, the user base grew quickly because the competing project had no documentation." \cite[p.6]{Dagenais:2010:CED:1882291.1882312}
Although this study provided insights into effective documentation practices, the study's qualitative methods were insufficient to draw solid conclusions. In the study's historical analysis, the authors "manually inspected more than 1500 revisions of 19 documents selected from 10 open source projects."\cite[p.1]{Dagenais:2010:CED:1882291.1882312}. Nineteen documents is hardly enough to draw serious conclusions from but can suggest patterns in how documentation is made that warrant future research. The project's authors interviewed 12 contributors to and 10 users of open source projects. These interviews were about a half-hour long. Again, half-hour interviews don't prove anything, but they do give insights into some expert's experiences developing documentation.
Although this study provided insights into effective documentation practices, the study's qualitative methods were insufficient to draw solid conclusions. In the study's historical analysis, the authors "manually inspected more than 1500 revisions of 19 documents selected from 10 open source projects."\cite[p.1]{Dagenais:2010:CED:1882291.1882312}. Nineteen documents are hardly enough to draw serious conclusions from but can suggest patterns in how documentation is made that warrant future research. The project's authors interviewed 12 contributors to and 10 users of open source projects. These interviews were about a half-hour long. Again, half-hour interviews don't prove anything, but they do give insights into some expert's experiences developing documentation.
\section{Types of Documentation}
The study analyzed the pros and cons of different types of documentation.
The first type of documentation the authors analyzed are wiki pages. Wiki pages, like wikipedia, are web pages that anyone can edit. As you would expect, allowing anyone to edit a wiki page can be a bad idea. First, because anyone can edit the wiki, they "lack authoritativeness" \cite[p.5]{Dagenais:2010:CED:1882291.1882312}. Furthermore, because wiki pages become "less concise" \cite[p.5]{Dagenais:2010:CED:1882291.1882312} and even suffer from SPAM. According to the article, "24.1\% of the revision in Firefox"\cite[p.5]{Dagenais:2010:CED:1882291.1882312} were SPAM. Because of these problems, "all of the projects we surveyed that started on a wiki (4 out of 12) moved to an infrastructure where contributions to the documentation are controlled"\cite[p.5]{Dagenais:2010:CED:1882291.1882312}. Despite these problems, wiki pages are extremely effective at encouraging community evolvement, which is critical to open source projects. To prevent anonymous actors from SPAMing the documentation, but still allow community involvement, the authors suggested using a comment section and encouraging feedback through various channels.
The first type of documentation the authors analyzed are wiki pages. Wiki pages, like Wikipedia, are web pages that anyone can edit. As you would expect, allowing anyone to edit a wiki page can be a bad idea. First, because anyone can edit the wiki, they "lack authoritativeness" \cite[p.5]{Dagenais:2010:CED:1882291.1882312}. Furthermore, because wiki pages become "less concise" \cite[p.5]{Dagenais:2010:CED:1882291.1882312} and even suffer from SPAM. According to the article, "24.1\% of the revision in Firefox"\cite[p.5]{Dagenais:2010:CED:1882291.1882312} were SPAM. Because of these problems, "all of the projects we surveyed that started on a wiki (4 out of 12) moved to an infrastructure where contributions to the documentation are controlled"\cite[p.5]{Dagenais:2010:CED:1882291.1882312}. Despite these problems, wiki pages are extremely effective at encouraging community evolvement, which is critical to open source projects. To prevent anonymous actors from SPAMing the documentation, but still allow community involvement, the authors suggested using a comment section and encouraging feedback through various channels.
The second type of documentation analyzed was getting started documentation. Getting started documentation is designed to get users to a base level of competency with a tool as quickly as possible. If getting started documentation is well written, it can also serve as marketing material. Unfortunately, "Finding a good example on which to base the getting started documentation, an example that is realistic but not too contrived, is difficult" \cite[p.6 Contributor 11]{Dagenais:2010:CED:1882291.1882312}. Good getting started documentation is useful when learning frameworks because it gives the user a simple example that's consistent the framework's principles but doesn't overload the user.
The final type of documentation is reference documentation. Good reference documentation should simply describe a single function. According to the authors for "atomic functions, reference documentation is the most appropriate documentation type to begin with because, as contributor C11 mentioned, it can be difficult to create getting started documentation that shows examples calling many functions" \cite[p.6]{Dagenais:2010:CED:1882291.1882312}. Libraries of atomic functions, for example rest APIs, are very different from frameworks that require a conceptual understanding of the framework to be useful. Fortunately, writing reference documentation is much easier than writing getting started documentation because it only requires documenting small parts of a code base.
The final type of documentation is reference documentation. Good reference documentation should describe a single function in simple terms. According to the authors for "atomic functions, reference documentation is the most appropriate documentation type to begin with because, as contributor C11 mentioned, it can be difficult to create getting started documentation that shows examples calling many functions" \cite[p.6]{Dagenais:2010:CED:1882291.1882312}. Libraries of atomic functions, for example rest APIs, are very different from frameworks that require a conceptual understanding of the framework to be useful. Fortunately, writing reference documentation is much easier than writing getting started documentation because it only requires documenting small parts of a code base.
\section{Documentation Management}
......@@ -47,13 +47,9 @@ An excellent way to avoid having a dedicated documentation team is to require al
Embarrassment-driven development can be useful on the macro scale also. The historical analysis discussed in the paper revealed that projects' documentation often gets bursts of activity over a short period of time. When interviewed, the projects' lead contributors said some of these bursts of activity were due to book deals. These book deals required the lead contributors describe how their project work which forced them to re-evaluate much of their documentation.
\section{conclusion}
\section{Conclusion}
In conclusion, the
doc types: wiki, getting started, reference
doc management: tools, requiring docs with contributions, documentation bursts
Although this paper doesn't make any strong conclusions, it is still useful to readers. First, it gives an understanding of what type of documentation (wiki, getting started or reference docs) is appropriate for a situation. Then it discusses the tools, protocols and general patterns involved when writing documentation. This paper would be very useful to anyone starting an open-source project.
\bibliography{finalPaperDraft}
......