Software Engineer at InVision. Full-Stack JavaScript dev, with passion for front-end development.
Psytrance DJ on weekends, playing in local clubs (yeah, that means: Goa Parties!) :D
Writing proper documentation is an iterative process. We usually use the following pattern at IBM:
Preparation and Writing a first Draft
Comment your code extensively, explain especially public facing functions very detailed. Explain parameter and types.
Then wait some days, extract the comments and use the extracted comments to write documentation. Try to not look too much at the code during this step, in order to avoid getting lost in details.
Proof Reading
Get somebody on board for proofreading and checking, if the documentation is comprehensive and whether other people who don't know about the code, can follow along
Write down any questions that came up by this person. Try to answer the questions within your documentation, try to avoid adding extra subsections, that only answer these questions in specific. Instead try to add information to your documentation, that clarifies the questions
To also answer related questions, keep the added information as general as possible!
(optional) Get another person on board
Repeat the Proof Reading steps with this person
Repeat the Proof Reading process with these persons
You can repeat the process until you find your documentation in a mature state. Dragging in more people ensures that the documentation not written in a way that is tailored to one specific reader. Each new pair of eyes gives you a new perspective on what is missing, wrong or difficult to understand.
I interned at NASA, working on statistical modeling and machine learning projects. Now I'm at Ferguson Enterprise, working on applying UX principles to internal tooling!
I really appreciate this detailed explanation. I definitely don't want to fall into the trap of writing docs that are only understandable by me. So I will follow the steps for the first draft. Then I ask the person who will do our code review if they will be open to give us feedback on our docs also.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
Writing proper documentation is an iterative process. We usually use the following pattern at IBM:
Preparation and Writing a first Draft
Comment your code extensively, explain especially public facing functions very detailed. Explain parameter and types.
Then wait some days, extract the comments and use the extracted comments to write documentation. Try to not look too much at the code during this step, in order to avoid getting lost in details.
Proof Reading
You can repeat the process until you find your documentation in a mature state. Dragging in more people ensures that the documentation not written in a way that is tailored to one specific reader. Each new pair of eyes gives you a new perspective on what is missing, wrong or difficult to understand.
I really appreciate this detailed explanation. I definitely don't want to fall into the trap of writing docs that are only understandable by me. So I will follow the steps for the first draft. Then I ask the person who will do our code review if they will be open to give us feedback on our docs also.