3 ms·
How about documentation? I was thinking about this the other day, as I was documenting an api, and I was writing as if I was speaking, explaining how I thought
by pedalpete 11y ago
How about documentation? I was thinking about this the other day, as I was documenting an api, and I was writing as if I was speaking, explaining how I thought about the problem rather than just the end-point details.
How do people feel about this.
Here's an example, but I didn't push the updates I made yesterday. https://github.com/favor/it https://github.com/favor/it
When I wrote for the high school paper, people always commented on how my writing was as if I was just having an conversation with them, so I've always tried to write that way, but I'm not sure it works for all formats.
- amk_ 11y agoThe linked documentation bounces between using 'I' and 'you' as subjects for examples. Get rid of the references to yourself in the docs -- the documentation should be neutral. Take the reader's perspective if a subject is required. In day to day business like setting development priorities or responding to issues on Github, you can use 'I'.
- pedalpete 11y agothanks for the feedback, I just wasn't sure about tone in docs, it's the first time I've really had to document something like this for public consumption. I will redo it.