There are lots of reasons to hate documentation:
The default CSS is beautiful and minimal, and will make your HTML documents look great. Easy HTML export. You can export the full document as HTML, or just selected text. Distraction-free Mode. This full-screen mode turns your whole monitor into a blank canvas for you to get some serious work done. Frequent updates. Commission calculator does a very simple calculation for you - it calculates the percentage-based remuneration. As with any Omni calculator, it can calculate either way - start filling in any fields and the other ones will be calculated for you. Take your Markdown skills to the next level. Learn Markdown in 60 pages. Designed for both novices and experts, The Markdown Guide book is a comprehensive reference that has everything you need to get started and master Markdown syntax.
Lots of hate for documentation.
So why do we still do it? Well, there are certain documents that most projects with more than one person should have (they don’t have to be separate documents) (I love bulleted lists):
There are other documents that you should consider under other circumstances, like:
I don’t mind writing documentation as long as it’s useful in some capacity. The problem for me was the overhead.
When you start talking documentation, especially documentation that needs to go through some kind of review and release process, there’s a lot of stuff that has to happen.
First you write the document, generally in Word, because “reasons”. Then you email it (or post on SharePoint) for someone (or multiple someones) for review. Then you get back at least one document hopefully marked up in a sane way (“I have Word 97 and couldn’t track changes so I printed it out and I couldn’t find a red pen so I used fuschia”) and incorporate the changes. Then, if your lead is pedantic (like me), more review to make sure you didn’t miss anything. Then you version the document and put it on SharePoint, where it slowly becomes irrelevant because nobody reads it, and it’s probably in the wrong folder anyway.
Oh, all of the editing is done in some inscrutable template that was designed for Office 2000 and we keep around for legacy reasons. Good luck using tables! Seriously, you should probably lock up any nearby sharp objects for a while.
Markdown lowers the amount of overhead.
If you’re not familiar with MarkDown, there’s a little bit of information about it under the rest of the post. Go look! But after you read about the results of using MarkDown on a Real World Project.
(Thanks to git_stats for generating me some sweet statistics)
We used MarkDown for documentation on the last major project I was on (started with one team of 8 for about 5 months, increased to 2 teams and 15 people for another 4 months). Here is the breakdown of commits per role:
| Role | Team 1 commit count | Team 2 commit count |
|---|---|---|
| Scrum Master | 71 | 0 |
| Tech Lead | 20 | 27 |
| Developer | 83 | 17 |
| Tester | 4 | 0 |
| Total | 178 | 44 |
And an activity graph, why not!
The documentation seemed to be updated more frequently and remain relevant longer than what I’ve seen on other similarly sized projects. Hp probook 6460b drivers windows 10. Often when a new team member came onto the project he would feel free to update any bits of documentation that had gone stale and push it through the review process. Launchpad manager pro 1 0 7 download free.
How to change font color on windows 10. With the lowered overhead of updating documentation, it became common to include acceptance criteria for a feature detailing what changes were necessary for which documents.
There were a few processes we could’ve put in place to help guide us for the following:
One of the biggest reservations of using MarkDown was the inability to use the client’s Word template for certain documents. Again, we probably could’ve written a single script to have the release process copy the text into the template.
Originally I had a dream of everyone using LaTeX, because LaTeX makes me feel warm and fuzzy. MarkDown was a compromise that seemed to work out pretty well. Guitar pro 5 mac free. The first team adopted the approach pretty readily, and there were no mutinies, so I consider the experiment a resounding success.
I’m curious to know impressions, feedback, if you’ve tried this on your project, how it went, etc. Comments are appreciated! And mandatory! If you don’t comment I’m going to stand behind your chair staring at you until you do.
MarkDown is a markup syntax that lets you separate your document into a source file (written in MarkDown) and a generated presentation file (which can be HTML, PDF, Word, and probably others).
Suddenly documentation is barely different than code. The source file can be kept in source control alongside your code. Since the markup is terse, it’s not challenging to review it using the same tools already in place for code reviews. And to release the document (or generate an artifact) you simply run the MarkDown through a document converter and do whatever you will with the generated HTML, Word, or PDF file (probably store it in the wrong SharePoint folder) (no, I’m not bitter).
MarkDown has a few ‘flavors’, or slight variations of syntax. Among my favorites are:
The core of each of these projects is very similar to vanilla MarkDown. kramdown adds support for filling the generated HTML with class and id attributes. GFM adds quite a bit to do with code formatting (as you can imagine). Pandoc includes a bit of hefty support for tables.
Image tricks pro 3 9. “But Mike,” I’m making you say, “what about tools for MarkDown?” Wow. I can make you say anything! “Mike, you’re super-handsome and your freshly laundered scent is beyond reproach!” Writing is awesome.
Because the text is fairly plain you can use whatever editor you want when editing the MarkDown.
There are lots of options here, depending on what flavor you’ve chosen:
0 
Star