An appeal to makers - why you should document your project, and how you can do it

RE: An appeal to makers - why you should document your project, and how you can do it

Bigtuna — Sun, 30 Aug 2015 02:31:52 GMT

Thanks, I decided to publish my journey with BLE after reading this post! http://bit.ly/1JpEc57

RE: An appeal to makers - why you should document your project, and how you can do it

Mahesh Venkitachalam — Wed, 05 Aug 2015 14:15:24 GMT

Thanks, Øyvind. I'll write a short introduction in my future posts. I've just added a new blog entry.

Regards

Mahesh

RE: An appeal to makers - why you should document your project, and how you can do it

Øyvind Karlsen — Wed, 05 Aug 2015 09:28:05 GMT

Hi Mahesh,

I think I might have formulated myself poorly. We're definitely glad to see your blogs, and encourage you to keep posting them.

I started reading the picture you provided here on devzone before I opened you blog, and for me it felt weird that there was no motivation/introduction like there is on your website, that is what I was trying to address.

Best regards,

Øyvind

RE: An appeal to makers - why you should document your project, and how you can do it

Mahesh Venkitachalam — Tue, 04 Aug 2015 04:52:02 GMT

Thanks @follower!

RE: An appeal to makers - why you should document your project, and how you can do it

Mahesh Venkitachalam — Tue, 04 Aug 2015 04:51:47 GMT

Hi Øyvind,

I understand your perspective, but I am not keen on reproducing my whole blog post here at the devzone. The main reason for that is I have taken great pains to format my article to make it readable. Cutting and pasting it here as text is not going to give the same appearance. If posting a link to my blog here is against Nordic policy, then I'd rather not post in this forum.

Regards

RE: An appeal to makers - why you should document your project, and how you can do it

follower — Mon, 03 Aug 2015 16:10:26 GMT

Duplicating my comment from there, here: :)

Nice writeup. This is a topic of interest to me as a result of improving (mostly :) ) my project documentation habits over time.

One suggestion on the ordering of items in your list of "primary reasons"--in my experience the strongest motivator (though selfish) when documenting a project is that the documentation is useful to the author first. When you know you're going to benefit it just seems to be a little more immediate gratification rather than the more altruistic "for others" motivation.

I prefer to think of it as a "selfish" motivation that benefits both yourself and the world. :)

I definitely agree that starting small is best--it's much easier to write something when you're only doing it a couple of sentences at a time.

A few years ago (before the creation of hackaday.io et al) I created a site named Labradoc intended to make it easier to create project logs like those you describe. Of course, I had grand visions of providing a service to other developers/makers/hackers but we're all too cheap to pay. ;) So, mostly it's just for me and enjoys from some retro 2011 styling. :D

Here's my list of projects: http://labradoc.com/i/follower

A representative example: www.labradoc.com/.../project-sms-text-scroller

And a more developed than normal example: www.labradoc.com/.../notes-esp8266

You've covered the points--both motivations and fears--well. Thanks for taking the time to write it up.

RE: An appeal to makers - why you should document your project, and how you can do it

Øyvind Karlsen — Mon, 03 Aug 2015 13:11:03 GMT

Hi,

Great writeup!

I am a bit confused by the picture(text) provided here on devzone. Preferably it should motivate the reader to open the link to your blog.

I understand that you want people to read your blog, and I think that it actually has a lot of great content. In this case I don't think it would hurt to double post your blog, both here and on your website, in the end on devzone you could say something along the lines of: "If you liked or found this post useful feel free to follow my personal blog over at my website."

Best regards,

Øyvind