Documentation An Engineering Problem Unsolved
-
Upload
schalk-cronje -
Category
Software
-
view
835 -
download
3
Transcript of Documentation An Engineering Problem Unsolved
![Page 1: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/1.jpg)
Developer UG Dec 2015
DOCUMENTATION: AN
ENGINEERING PROBLEM
UNSOLVEDSchalk W. Cronjé
![Page 3: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/3.jpg)
Way back in 1997…
![Page 4: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/4.jpg)
Information Mapping®Chunking - Information in small manageable units.
Consistency - Format, structure.
Integrated graphics - Diagrams & tables are part of thetext.
Accessible detail - Put what the reader needs, where thereader needs it.
http://www.informationmapping.com/en/
![Page 5: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/5.jpg)
2004…
Agile Documentation, Andreas Rüpling
![Page 6: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/6.jpg)
Knowledge Management ConceptsDocument Landscape
Wiki
Code-Doc Proximity
![Page 7: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/7.jpg)
CodeDoc ProximityThe further the distance between the code and the
documentation, the lower the probability of the
documentation being maintained.
![Page 8: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/8.jpg)
Desire #1We want to use the same editor for code & docs
so that we do not have to switch tools.
![Page 9: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/9.jpg)
2005…
Wellsprings of Knowledge, Dorothy Leonard
![Page 10: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/10.jpg)
Signature SkillsPeople will development affinities for certain tools
When the user has to fight the tool, the tool will not getused effectively (or not at all).
![Page 11: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/11.jpg)
WYSIWIG
![Page 12: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/12.jpg)
Desire #2We want to focus on content, not layout.
![Page 13: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/13.jpg)
Desire #3We want to use one source to publish to multiple formats.
![Page 14: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/14.jpg)
Tracking changesEngineering has already solved this problem.
Source control (Git, Subversion and others).
Easy to diff between changesets.
Collaborate with multiple commits and merging.
![Page 15: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/15.jpg)
Desire #4We want to store document source in a textual,
non-proprietary format, so that we can use existing
tools and track the changes.
![Page 16: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/16.jpg)
Desire #5We want to concurrently, collaborate on documents
and modify them without fear.
![Page 17: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/17.jpg)
AutomationCI & CD and standard engineering practices.
Commit → Build → Feedback → Publish
![Page 18: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/18.jpg)
Desire #5We want documentation to be built
and published automatically.
![Page 19: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/19.jpg)
Desire #6We want our documentation to be
included with software publications.
![Page 20: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/20.jpg)
We want…to use the same editor for code & docs so that we do nothave to switch tools.
to focus on content, not layout.
to use one source to publish to multiple formats.
to store document source in a textual, non-proprietaryformat.
documentation to be built and published automatically.
documentation to be included with software publication.
![Page 21: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/21.jpg)
2014… State of Simple Publising
![Page 22: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/22.jpg)
Introducing Asciidoctorhttps://github.com/asciidoctor
http://asciidoctor.org
(Go explore yourself happy)
![Page 23: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/23.jpg)
Why?Focus on content, not formatting.
Source-control friendly.
No proprietary source format.
More powerful than Markdown, including
Github MD.
Leanpub MD & Markuva.
More user friendly than RText or LaTeX.
No need to fight Docbook.
![Page 24: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/24.jpg)
FlavoursAsciidoctor (Ruby)
Asciidoctorj (JVM)
Asciidoctorjs (Javascript)
Original Asciidoc (Python)
![Page 25: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/25.jpg)
2015… State of Asciidoctor
![Page 26: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/26.jpg)
Drawing supportPlantUML
Ditaa
Shaape
BlockDiag, SeqDiag, ActDiag, NwDiag
GraphViz DOT
Via asciidoctor-diagram module
![Page 27: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/27.jpg)
Drawing support +-------------+
| Asciidoctor |-------+
| diagram | |
+-------------+ | PNG out
^ |
| ditaa in |
| v
+--------+ +--------+----+ /---------------\
| |-->+ Asciidoctor +--->| |
| Text | +-------------+ | Beautiful |
|Document| | !magic! | | Output |
| {d}| | | | |
+---+----+ +-------------+ \---------------/
![Page 28: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/28.jpg)
Drawing support
![Page 29: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/29.jpg)
Source Code Highlighting
[source,cpp]
----
int main(int argc,char** argv) {
std::cout << "Hello, world!" << std::endl;
}
----
int main(int argc,char** argv) {
std::cout << "Hello, world!" << std::endl;
}
![Page 30: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/30.jpg)
Buildtool supportMaven
Gradle
Ant
Leiningen
SBT
Grunt
![Page 31: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/31.jpg)
ProjectsA number of projects use Asciidoctor for documentation
complete with tested code snippets, including:
Groovy Language
Spring
Griffon
![Page 32: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/32.jpg)
Actively in the worksAsciidoctor → Leanpub
Asciidoctor → Mallard
Asciidoctor → LaTeX
Asciidoctor → Pdf
Asciidoctor → Epub
![Page 33: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/33.jpg)
About this presentationWritten in Asciidoctor (1.5.3.2)
Styled by asciidoctor-revealjs extension
Built using:
Gradle
gradle-asciidoctor-plugin
gradle-vfs-plugin
![Page 34: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/34.jpg)
Demo
![Page 35: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/35.jpg)
Books in Asciidoctor
Built by AsciidoctorJ + Leanpub backend (1.6.0-SNAPSHOT)http://bit.ly/1iJmdiP
![Page 36: Documentation An Engineering Problem Unsolved](https://reader031.fdocuments.in/reader031/viewer/2022021814/58f304c01a28ab50018b460f/html5/thumbnails/36.jpg)
Try it outInstall via Rubygems
Command-line asciidoctorj
Download OR
SDKman ( )
Docker
asciidoctor/docker-asciidoctor
Browser plugins
Build tools
http://sdkman.io