LibreHealth Toolkit Documentation: First Steps

My primary task for this summer Outreachy internship is helping to optimize and update the documentation for the LibreHealth toolkit and create a static website using Sphinx documentation generator.
I had very little experience writing documentation and never used something like Wiki pages or Sphinx. All my READMEs were regular README.md files laid out with Markdown. When I started reading about Sphinx, I discovered two things:

  1. There is no «official» Markdown specification, Markdown rules and rendering can differ depending on a platform.
  2. Sphinx uses reST (restructured text), which is a lot like Markdown but has a clear specification and additional features.

I always want to try out things myself so I found a tutorial on the Sphinx website. It outlines how to create simple documentation with Content tree and links to sub-documents and instructions on how to build and run it locally. The tutorial is well-structured and you don’t need to have specific knowledge to go through it.
Another thing that I needed to do, was installing an IDE that supports Java. I have no experience with this programming language but based on previous revision on the project documentation and my experience working in JetBrains’ IDEs, I chose IntelliJ Community Edition. Community edition doesn’t have all features and integration options of the professional edition but it can be used for free and is enough as I was not going to write much (if any) code.
I’m relatively new to Linux and when it comes to installing programs that cannot be installed with apt-get install, I get stuck. I read a manual on installing IntelliJ on Ubuntu from an archive but on the last step I found out that I don’t have a file they were asking to move. There’s a lifehack for those who are like me: you can use Ubuntu Software Center and look for the needed program. It worked for me and in just two mouse clicks I got a running IDE with a familiar layout (all JetBrains’s IDEs that I’ve seen have a similar layout, settings, and tools).
It’s a little weird to see the code in a language you don’t know. When I just started to learn to code, everything looked bizarre and I didn’t understand a thing. Now when I try to read a Java code, I notice familiar patterns like loops or functions and classes but they have different syntax and it’s not always clear what happens in the code.
People often told me that it is much easier to understand or learn your second, third or fourth programming language and it’s totally true! When you understand and can see generic patterns, you can try writing things you can write in JavaScript using, for example, Go. I’m not saying that this is the best idea because different programming languages require you to use different approaches and in most cases, you shouldn’t write in JSy Go.
So learning a little about the tools I will be using and setting up work environment on my machine were the first steps of my summer internship. I’d use the same steps for any new project:

  • Learn the main tools.
  • Set up work environment.

You will both have a possibility to run a project locally (if it can be done) and become familiar with the tools others are using.

You can see the documentation website that I’m working on here: https://docs.librehealth.io/.

Добавить комментарий

Заполните поля или щелкните по значку, чтобы оставить свой комментарий:

Логотип WordPress.com

Для комментария используется ваша учётная запись WordPress.com. Выход /  Изменить )

Google photo

Для комментария используется ваша учётная запись Google. Выход /  Изменить )

Фотография Twitter

Для комментария используется ваша учётная запись Twitter. Выход /  Изменить )

Фотография Facebook

Для комментария используется ваша учётная запись Facebook. Выход /  Изменить )

Connecting to %s