Tag Archives: writing

Even if you can’t write well

Posted by Jacob Santos on November 3, 2007 1 comments

And I speak of this because I’m one of those who can’t write well. The philosophy I’ve always had was that someone would eventually come along, take a look at the crap you wrote and fix it. A novel concept, but I’ve seen it in action.

I try to write documentation well enough, but it is clearly fascinating skill others have to clear issues up and make words and paragraphs look pretty. Organization is key I think. By placing code in certain places, you can give context to paragraphs in a way that just blows the mind.

What I mean is that even if you may not think what you write would help someone, there are enough people that might stumble upon the code to correct the wording. The key with writing documentation is to write well enough for most people to understand what you are trying to get across so that someone who wishes to play editor may do so accurately.

Possibly Related Posts:


Will Documentation Writers Be Remembered?

Posted by santosj on October 21, 2007 1 comments

Probably not. I think the ends far outweigh the perceived gains from being “recognized.” One of the major advantages of PHP is its heavily documented functions and its almost one stop shop for finding everything you’ll need and want to know about a function. I don’t know who those people are, but I have a lot of love for the time and energy they put in.

It is possible to find their names, but I don’t think many would put in the energy. Coincidently, not many will put in the effort to document a project. It just takes too much sweat, blood, and tears.

It is rewarding in the metaphorical sense, and if you have to pay penitence for not documenting past projects. Documenting another’s project is one way to avoid the whip. It is actually relaxing, in the sense that I can spend hours, “Holy crap, it is 3am already? Just a few more hours and then I’ll go to bed.”

The project I’m currently documenting probably be the same. People may thank me without knowing my name, but you know I won’t mind. If only to make up for past mistakes and learn new habits that will better benefit future ones. The reward for me, is the knowledge gained from the insight and from that I think I’m doing myself more good. It is how I can justify non sexy work, such as documentation.

Possibly Related Posts: