Documentation is my gateway to coding

Jess Lee on December 18, 2018

Being a founder is one of those roles where you're giving feedback on basically everything, while also trying to get a couple of things done each... [Read Full]
markdown guide
 

I love writing documentation, not just from an API point of view. I'm given a lot of leeway as to how I implement the back-end UI for things and I try to keep screenshots and tutorials up to date for CMS administrators and so forth.

A couple of jobs ago I worked with someone who was, like, a professional technical writer, and that experience has made me push for my bosses to employ TWs everywhere I've worked. Haven't made much headway, but I keep trying.

 

Most developers hate writing documentation as far as I can see on projects I've managed in big corps mostly because it's a daunting process and it takes too much time to maintain (I mean true doc not just useless comments) so I'm working on a format and above all tooling to ease this for all programming languages - there are already javadoc for java for example but it will be a layer above.
It's far from being there because I have a lot of other stuffs, at the moment there is a core format here readable.red - that I have to better document I know :)

 

Documentation is a great way to contribute to open source too. If you use something a lot and are a little scared of opening a PR with code, writing or updating docs are usually always appreciated and have a high impact on the people who read the docs.

 

This is exactly what I have been doing. Sometimes it's little things like nitpicky syntax, accuracy or wording.

 

Works for me too - I find that summarising what I've done so far in a problem area helps me get a better view and gets me back into the challenge, whilst also helping with the big red bus/lottery win scenario!

 

Technical docs and end user documentation helps me see in different contexts and points of view which provide more data or thoughts.

For me to solve issues I'm usually writing sometimes in a journal like style to break down the issue so I might be able to see a trend in though and I usually write why a few times and try to solve the why. The why sometimes points me in the direction to solve it within its context without going crazy (sometimes only a little crazy). Sometimes the why leads me to more questions to solve.

I've been handed bugs that seemed random but managed to get them to replicate and for that I had to write trends and hypothesis and tested these. Sometimes this can be found in a teaching style of documentation -- almost textbook style as opposed to very short. More like guides.

These methods of writing all help my ability to code. I'm not your more elegant coder but sometimes I'm fairly non-linear in the style.

 

How do you write your docs?

Do you people include failed attempts, considerations and whies in your documentation? The process things you tried first before eventually deciding to implement it as it is. Things that failed.

My documentation is always strictly technical / api reference-like while others write a novel about the journey.

 

I do rather enjoy writing documentation...except for the year I spent working on virtually nothing else.

 
 

Totally! It's like stretching before a run - getting back in the workflow groove first before digging into the code.

 

Ah what a good idea! I usually switch between design and dev and I get frustrated when I don't get to jump in the code right away. I might try to do this.

Thank you!

code of conduct - report abuse