#Issue132
2 posts

Don’t be a jerk: write documentation

Documentation can be minimal and yet helpful. Take whatever you have in volatile formats (email, chat logs, shell I/O) and paste it into more durable ones (README files, diagrams, websites, FAQs, wikis).
Read more

Don’t be a jerk: write documentation

  • Documentation can be minimal and yet helpful. Take whatever you have in volatile formats (email, chat logs, shell I/O) and paste it into more durable ones (README files, diagrams, websites, FAQs, wikis).
  • Document based on your audience:
  1. For newcomers, focus on what it does, why you wrote it, who should be using it and for what, how it should be used (how to build, configure, run and get started), and where additional information may be found; do not display the source.
  2. Regular users could do with a reference manual, examples, EDoc/JavaDoc/Doc, wiki or website, and API descriptions.
  3. Contributors should have access to the source repository, as well as project structure and architecture (where to find out about specific functionalities and where new features should go), the project principles, tests, issues, and a roadmap.
  • An easy way to get started is to imagine you are talking to a new user. Then vary the user and add different scenarios (of their business context and experience/knowledge, budgets) to expand the documentation until it is comprehensive. Finally, you might split it up into categories for different people or reimagine/format it for different media/platforms.
  • Another approach is to find a problem a user might face and show them how to solve it.

Full post here, 11 mins read

How to feel less overwhelmed as a developer

Identify the specific problem - be it too steep a learning curve, too much information incoming, too many responsibilities, peer pressure or your own expectations of yourself.
Read more

How to feel less overwhelmed as a developer

  • When you feel overwhelmed, either there is too much going on at once or you are overstimulated. Refocus and reprioritize.
  • Identify the specific problem - be it too steep a learning curve, too much information incoming, too many responsibilities, peer pressure or your own expectations of yourself.
  • Zero in on your key goals, set your boundaries, focus your ambitions, and recognize what’s not really relevant to you.
  • Find a process for self-education. Don’t try to memorize everything, learn where to find the right information. Make a list of what you don’t know, and add to it every time you come across a new idea or a skill you don’t have. Sift through the content and establish your key resources so you aren’t overwhelmed.
  • Beware of getting overwhelmed by other people. Make sure you have a balanced perspective on social pressure. Know that a lot of people write bad code, even great developers in great companies. People have different priorities and you don’t have to keep up with theirs. Remember that people will write about what is possible but you don’t need most of it on a day-to-day basis.
  • Work smarter by spending time on core skills like problem-solving, critical thinking and testing. Use proper project management tools to plan, manage tasks and track bugs. Take breaks for fresh air, exercise, and conversation so you don’t lose sight of the big picture. Ask your community for help with good resources, pointers or support with your workload.

Full post here, 9 mins read