Below are some details of a documentation strategy that i've formed over the past couple months (and still working to improve):

The first hurtle is getting past the feeling that documenting everything only serves to be a bottleneck to any progress. For a long time, this kept me from documenting hardly ever.

The simple fact is that it IS a bottleneck. But only because I don't know how yet

• after working on improving documentation skills, documentation eventually grows out of its bottleneck issues and becomes a valuable part of the whole process rather than a separate hinderance.

Settling into a process has been the most helpful part of the documentation strategy.

While grunting through the pain, always consider your process. Always think of ways to remove potential causes of distraction, delay, multi-tasking confusion, etc.

• on "multi-tasking confusion"
  • this is just what I call it when I find myself researching, wanting to document something, shifting to documentation, and then finding myself pausing to consider "wait, do i document now or do i try to flesh out some more details in my research?"
  • it's easy to get to this point and be indecisive, and realize I've taken a few minutes just thinking about when to do what
  • when i get here, I simply document what I know and then get back to research
    • this was not immediately beneficial in terms of efficiency, but over time, it became more natural to know when i reached a good point in my research to document my findings
    • and then rather than thinking in terms of "do i document now or ... research," it has become "documenting is an integral part of research"

Over time, by continuing to force myself to incorporate documentation in my processes, i've found many ways of tweaking my processes to my advantage such that documentation has become a interwoven process that fits more or less seamlessly into most of the tasks I perform.

Ongoing Improvement

• I've noticed a sort of phased improvement overtime - I'll make some changes that make a big difference, go for awhile with the adjusted process, and then reach a point where a few more changes come to mind, and then enter a new, further improved documentation process
• I don't really see ever reaching a point that I think I'm done improving my process, but I do see reaching a point in the future where a current phase of a given quality in my process lasts a long time before I come up with more worth while improvements

A point of View: everything is research (...huh?):

• reading an interesting tech blog? research; catching up on yesterday's news? research; etc.
• in school I hated research ... what I didn't realize is that I actually didn't mind research, I just hated documenting what I learned (and that's because it sucks to work hard at becoming good at something; but when you get there, it's worth it)
  • disclaimer: i'm not "there" but I'm working on it, and the hard work is becoming less hard over time

In practice:

• Obviously we can't document literally everything, so we pick and choose, but I've been forcing myself to choose to document more and more research items
  • initially that was a burden, but over time it has become less cumbersome
• I basically try to note anything as I research that I catch myself having a "hmm this is confusing" or lightbulb moment or "ah this relates to that other topic" type moments
  • this has really helped me to eventually make sense of the more complex topics that require gathering information from many different sources and distilling the knowledge into something useful

It really helps to spend a lot of time reading blogs/articles of people who do this for a living (and try to emulate what they do)

• NOT professional journalists or even professional tech bloggers
• professional tech people (who's job is NOT blogging but working in their given tech field) who have technical blogs

The reason I think of tech bloggers is that this type of documentation is similar to what I'm aiming for

• I want to document about technical topics (typically related to programming and/or technology)
• I'm not technically seeking to have a blog and a reader base, but I AM seeking to have a useful knowledge base as a valuable reference

Scott Hanselman (my freakin hero basically, no big deal) is a shining example of awesome documenter. Reading his tech blog is just a pleasure and incredibly enlightening - always. The guy does a million things a day and produces blog articles on complex subject matter very frequently. And his articles include excellent sources as well as insightful pointers.

• my goal is not to have a blog the world reads, I just want to learn from him and see if I can improve myself by trying to take a page from what I can observe of his work

related note: perfection can be a time-waster

• don't spend copious amounts of time on wording/phrasing; make it clear enough to understand if visited on a later date, and be satisfied with that
  • this is a very tough one for me, I tend to spend too much time attempting to re-improve my wording (so a recent focus I've had is to force myself to stop that if possible)
• reading pro tech bloggers (the good ones like Scott), I've noticed that the quality of their writing in terms of grammar, spelling, typos, etc. is not perfect
  • it's not BAD at all, it completely readable and clear
  • it's not riddled with errors, it's just not incredibly rare to see a typo
  • the point here is the pro's know what to spend their time on, they are VERY busy, so
    • they get the message across
    • they make sure it's clear
    • they spend a reasonable amount of time on the grammar/typo stuff
  • nobody, and I mean nobody, reads Hanselman's blog and thinks "wow, I saw a typo there, he must not be very skilled or know what he's doing"
  • to the contrary, thousands of readers read his articles and acclaim the value of the content he conveys

Follow pro tech bloggers (find the good ones, there are sucky ones) and gather little nuggets like this one by observing how they document.

This notion is common in the context of communication, and documentation is a form of communication - probably the most common form if I think about it: texts, emails, pic messages, IMs, Twitter, Facebook messages/posts, Instagrams, web pages, books, images, videos, etc.

About the motto "less is more" in documentation:

• it's not about saving yourself time/effort in documenting
  • it's easy to think of it this way and inadvertently end up with insufficient information
• it's about saving your reader time/effort in reaching an understanding of the documentation
  • my "reader" is usually me reading my own documentation
• it describes a goal for communication
  • the goal is that the message is as clear as possible with the receiver of the message reaching an understanding with as little effort as possible
• and focusing on achieving this goal usually results in a lot of time and effort on the part of the message sender (that's me and i'm sending a message via my documentation)

How do I get to "less is more"? ... well. I start by not caring about achieving that

1. I include AS MUCH information about my given topic as possible
2. then I work on organizing it
3. then, with careful consideration, I work on reducing the information to include only what is necessary
   • (long process if done right IMHO)
4. then I work on my wording/phrasing to achieve greater clarity and conciseness
   • (long process if done right IMHO)

When is reaching this goal worth all that time/effort? not very often IMHO

• When it's not worth it
  • Personal Documentation: e.g. these wiki articles; these are for my reference, but if others see it, awesome
  • Professional Documentation (e.g. user guides, tech articles): arguably getting closer here, but my priority is still the content over actually achieving the highest level of conciseness
  • Emails: kinda depends on the situation, but there really aren't as many emails that require this extreme level of careful crafting as there are emails that are worth a moderated version of this refinement process
• When it is worth it
  • Academia: I rarely (if ever) write scholarly works, so I don't have to reach that level of refinement often
  • Official Publications: again, not common for me
  • nothing else comes to mind (not that I've spent much time trying to come up with scenarios, I'm sure they exist)
  • Key: if I'm writing in this category, I'm really working on a more formal type of documentation than this article is targeting

What work IS usually necessary?

• IMHO, in most cases, step 1 and 2 from above gets the job done well
  • for fairly complex documentation, careful reduction can be very helpful, but NEVER at the cost of losing important, pertinent information
  • the emphasis here is on creating material which is the whole point of documentation

Bottom line: often, less is just less (unless you put forth a questionably-worth-while large amount of effort)

So the theme is ...

• Very simply, I force myself to document as much as possible
• always scrutinize and attempt to improve my process
• and over time see my refined process increasingly save me time and effort

The value I've gotten out of a process that works for me and some extra attention in some specific areas (listed below) is that whenever i'm working on documentation, I spend any and all time and effort focusing only on the information and minimal to no time and effort on formatting, distribution, etc.

So, I'm able to:

• document more comprehensively
• document more spontaneously whenever I discover something worth while
• document without stunting progress in my research or regular work
  • this is a big one; a common reason to NOT document is feeling like I'll lose my train of thought as I research
• keep my documentation more organized
• keep my documentation more logically interconnected where appropriate

Formatting isn't worth the effort, but if I could snap my fingers and have good formatting, I'd take it, because it DOES help.

Enter Markdown...

I Use VS Code as a text editor to leverage its nice built in Markdown viewer

• There is a very small learning curve for markdown and the payoff is huge
  • the payoff is that I don't even have to snap my fingers for formatting - it's literally happening while I document!!!
• This allows me to spend almost no time on formatting while still actually having a nice readable format
  • If I need to throw the information into a SharePoint wiki, I can copy the rendered formatting (from within the VS Code Markdown viewer) and paste it into SharePoint, and the formatting remains nearly completely intact
  • If I want the information in my github wiki, I just push it to my wiki repo since github renders the markdown
• Extensions
  • VS Code has some excellent extensions that I've found helpful to me in this area
  • there are TONS of them though, so I am pretty picky

• i've basically got a "wiki" folder that contains folders for any categories of research im working on to help myself stay organized
• separately, i've got git setup so that I can easily push docs to my github wiki
  • I don't work in the local git repo, I just put the files in my local repo when they're ready
    • this way, I avoid accidentally push a wiki page I didn't intend to

• I wrote a python script to save me time by automatically creating a table of contents based on my wiki file structure (this tool is on my github)
• There are some much more useful and powerful tools that would probably provide a better solution, but for now I'm trying to start with a home-grown approach so I can:
  • learn a little about myself in terms of what habits benefit me most
  • get an idea of what kinds of features I'd most desire when looking for a better over-all solution (such as blog tools, static site generation - e.g. Jekyll)