Markdown format is rapidly spreading and its support is becoming a “must have” for the wiki provider and not only for them
From developers perspective the fact that GIthub supports flavour markdown has forced them to learn it (that is also my case) and currently the markdown know-how is considered a plus in development skill (assuming documentation as part of it).
However Markdown has dramatically simplified the way to write (especially) technical documentation, making such task pretty straightforward
As developer I consider strategic keep in-sync both project & documentation (in particular concerning open source project), but usually, such stuff is perceived as boring and requires an extra effort that not always is well estimated. So one of suitable solution is consider the documentation at same level of code and part of development.
Below I’ll share with you experience concerning my documentation fight, so … let’s start
In my case, using Confluence for documentation, I was forced to switch from IDE to wiki's editor for its writing and for such reasons usually I waited to do it at the end of coding (making the biggest mistake)
While ago, to find a way to mitigate such problem (dev2doc) and properly keeping in-sync code & documentation concerning my java projects, I developed (and actively maintaining) the maven confluence plugin allowing to deploy project’s documentation directly on Confluence as part of project’s lifecycle. This allowed me to save a lot of time and also deliver a better documentation.
The plugin requires that documentation has to be written in Confluence wiki but (as said) the Markdown affirmation has push me to take in consideration a way to use it.
At first moment such improvement was a “nice-to-have” but, when I’ve found out that, thanks to doxia-module-markdown, also the maven site could be generated using markdown, I realized that was close to achieve a sort of “Write once read everywhere” and then I’ve fastly released (from version 4.4 Sep, 2015) the support for markdown relying on amazing Pegdown project.
Becoming markdown the “de facto” standard there are available a lot of viewer and editor that make simple working on, moreover the main code hosting service as Github, Bitbucket, Sourceforge support it, so there aren’t excuses to avoid to learn it.
Indeed I suggest to looking for tools, like maven confluence plugin, in order to deeply integrate documentation in your development lifecycle, increasing software quality and, using markdown, also get value from Write Once Read Everywhere