Documentation as a project
Why documentation can’t be the project ?
Introduction
This article, based on my experience, demonstrates approach of organizing
documentation in your project aiming following:
- Make easier s/w project transition to support
- Get single entry point for updates and info
- Get project documented from multiple angles
- Get your stakeholders involved
- Get your developers involved
- Get your ops involved
- Get your testers involved
Background
I am in software development for more than decade now. I used to work in a
different teams and on different projects, including the one, that was
transferred on support from other teams and even companies.
On of the biggest and most usual problems faced were lacking of project
documentation. In number of situations it was cause of the longer time needed to
take ownership over project. This is not usually failure of the team, sometimes
documentation is just not included into budget.
That’s why I always tried to include portions of the knowledge for future
support (even for myself in a few months or years)
Most often we are working with subset of diagrams, which are called informally
4+1 architectural view set, i.e.
Development view: Component, Package<br> Logical view: Activity, State,
Class<br> Physical view: deployment<br> Process: Activity, BPMN<br>
Scenarios: Use Case
In a bigger projects, usually project manager decides what visualization
packages are used depending on his experience. I used to draw diagrams in MS
Visio, Edraw, yEd, Openoffice Draw, also number of online tools like Gliffy,
Lucida charts, draw.io etc.
Common issue I had — is constant feeling, that I would draw them much easier
with pencil and scan afterwards. On some more complex diagram set another
question I had was also “Hey how did I spend my working day today” As
diagrams also need to be constantly updated as software evolves, it was
sometimes hard to track differences in proprietary binary formats or even
constantly check diagrams differences online (like Gliffy, where versioning is
supported). On some projects we had google docs with number of diagram file
versions uploaded. If project used Confluence — it was probably the best case of
ever possible. On some projects we had just wiki provided by bitbucket …
For a quite long time I was looking for consistent approach, how to keep my
diagrams sources as simple as possible. Basically I had very basic set of
requirements:
- to spend minutes to draft diagram
- to be able to see history of changes in source control
- ideally be able to combine diagram with code
Let me share with you current state of my findings:
Tool #1: Plant UML
Site: http://www.plantuml.com/
Dependencies: java, GraphViz package
Diagrams supported: UML set & a bit more
Tool is able to draw full set of UML diagrams, which makes it almost ideal,
although your sales person probably will not be happy from look. But for
purposes of documentation they are perfect:
But what is great, is that diagrams sources are pure text:
This allows you to put them together with code, for example as a block comment
to your module, easily track changes in a source control system, etc
Tool has number of integrations with variety of software:
http://plantuml.com/running from IDE, to wiki or
confluence.
You can try interactively how to draw diagrams now at
https://www.planttext.com/ or view few pre-created
diagrams at http://bit.ly/plantdiag
Tool #2: Blockdiag
Site: http://www.blockdiag.com/
Dependencies: python 2+<br> Diagrams supported: blocks, sequences, activity,
network, rack, packet structure.
Activity diagram, for example, looks a way better than one generated by plantUML
Compared to PlantUML diagrams look better, but cons are that number of options
is much lower. From other hand, there are some specific kind of diagrams, like
packet structure, rack or just graphs — that make this tool ideal.
Tool #3: Sphinx doc
Site: http://www.sphinx-doc.org/<br> Dependencies:
python 2+
Pros: universal, including your own custom code to build the pages
Cons: plugins matter
PlantUML and Blockdiag are perfect tools, and can be used on their own, to
generate diagram images that you insert into your wikis afterwards.
But if you are looking for a full cycle solution for your project documentation
— take a look on Sphinx doc.
This is universal solution to be engine of project documentation for project of
any size, and my compete with wiki, confluence, and similar tools
Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF
versions), ePub, Texinfo, manual pages, plain text
Extensive cross-references: semantic markup and automatic links for
functions, classes, citations, glossary terms and similar pieces of information
Hierarchical structure: easy definition of a document tree, with automatic
links to siblings, parents and children
Automatic indices: general index as well as a language-specific module
indices
Code handling: automatic highlighting using the Pygments highlighter<br>
Extensions: automatic testing of code snippets, inclusion of docstrings from
Python modules (API docs), and more
Contributed extensions: more than 50 extensions contributed by users in a
second repository; most of them installable from PyPI
Per my humble opinion, pros are:
- Well known, themable
- Wide range of plugins and extensions
- Your own custom page generators
- Advanced rst syntax
At that moment I can’t skip cons you should take into consideration:
- “ReadTheDocs” theme
- You need carefully select plugins
- Development efforts at the start
- Confusion on Markdown — if you use markdown each day, switching between rst and
markdown will be a pane
When I say, that “ReadTheDocs” theme is a cons — I mean, that probably the only
existing fully adapted theme for documentation is the one you saw hundred of
times:
Project Docs bootstrap boilerplate
As a result of experimenting I came with solution based on tools demonstrated
above. The demo of the deployed artifact probably tells more than a few
paragraphs:
http://labs.voronenko.info/ProjectDocs/
Github:
https://github.com/voronenko/projectdocs
“Ready to go” configuration : either in form of local install (plantuml &
blockdiag need to be installed in the system) or via Docker (alpine based with a
small footprint) — it allows to start your documentation project in less than
hour.
Integration with your code
You can have dedicated repository for project documentation project, if your
project consist of few repositories, or you can just have a documentation branch
in scope of project code repository
The same source flow
If you make use of gitflow or similar code approach, you would benefit from the
same flow in documentation project — pull request, code review, release…
Zero start: clone and modify
Boiler plate includes:
- Common page and diagram examples
- Build routines
- Build routines for docker
- Package routines
- Deployment draft for Gitlab/Jenkins
Integration with build pipeline
You fully control how and where you build your project. Boiler plate supports:
- Local build (run on your own) — packaging and versioning logic on
- Docker build (run with dockerized sphinx environment) — for use, for example,
with Gitlab
Integration with deploy pipeline
You have full control where and how you deploy your documentation.
Boiler plate supports deploy with Ansible (jenkins, bamboo, etc) and includes
draft of ansible play to do so. Example for gitlab is also included.
Publishing bonus
For local build, solution also supports such build artifacts like mobi, epub and
pdf — which allows you to publish your documentation in a offline form and
distribute together with your solution
Summary
If you like approach, you are welcome to start adopting it now. Please find
below basic items of current article in form of presentation
Why you can’t write software that parses code that is written in integers and convert it into english definition of it’s operation? Because that’s how you would crack a bible and you are educated idiot.
Can you rephrase your point / question ?