Re: Refactoring the Project Documentation


My name is Prubhtej Singh & I'm a Senior Year student at GGSIP University, Delhi, India. I'm pursuing my bachelors in Information Technology. I'm an Ex-OSS contributor at NRNB for Google Season of Docs 2020, wherein, I had written the documentation for SynBioHub and the link for the same is here: - wiki-synbiohub-org(replace "-" with "."), I was mentored by Prof. Chris J. Myers, Chair, ECEE, CU Boulder, US.

I'm an Ex-SWE Intern SBOL Industrial consortium, US and was working on a software by the name Excel2SBOL.

I've got a good command over Python, Machine Learning and Javascript, & given my experience with NRNB, I'm comfortable with static site generators, as well.

I'd like to formally put forward my interest for the project: - Refactoring the Project Documentation & would request to have a chance to have a conversation with the mentors, before beginning to start drafting the proposal.

Hope to hear from you soon.



My LinkedIn Profile: - (Prubhtej-singh)

Requesting Daeraxa & Laurent for their comments and suggestions.

Happy to see you are interested in the project but I don't see any PRs or contributions so far:

Before you can be accepted as a contributor we expect you to write some code and link that work on your proposal.

Are there any issues you are planning to work on or can link us to?

Yes, surely.
The first thing that a user observes while going through Joplin's docs is the sheer amount of data it has on a single page. If you've had the chance to got through the documentation that I've mentioned in my introduction, it simplifies the whole workflow as well as giving the documentation a nice and simple look.

The base issue according to me, is to migrate the existing documentation to such a way that it looks organised. Hence for that I'd like to suggest if we can use the static site generator Hugo. It has got loads of themes specifically for documentation and it is pretty simple to get up and running.

Yes, that is the entire goal of this project idea. So long as the proposed technology for the framework can be used to create static html from plain markdown and utilise github actions for CI then it is most likely suitable.

I agree to the point that you've made.
Hence, the first step is for us to decide which static site generator do we want to employ for this project and which documentation do we want as the base case.

If you'd allow me, I'd suggest that we use Hugo which satisfies all the requirements that is of building static HTML from plain markdown and we can utilise GitHub Actions for CI.
The base case, for that matter there are several options available. But to keep things simple and compact, I'd like to take the SynBioHub-documentation as the base case.

Requesting your opinion.

As before, the most important thing we need to see is contribution to the project so that is really where your focus should be before diving too deep into the specifics of how this might be done.
You also need to have a good grip on how the website is currently built.

Agreed. But for that, we need to set up the static site generator. If you want me to that just now, it can be done. As per the existing website, we only need the content, that shall go into the markdown.

So, do you suggest, I get the static site generator, up and running that contains some documentation from the existing one?

No, that is work that we expect post proposal and post acceptance of you as a contributor which is unlikely if we don't see contributions to the project as stated before

Understood. Are there any specific issues that you want me to deal with, as of now?

Only as listed in the guidelines, look through the issues and find something (triaged with high/medium/good first issue) that you wish to tackle

I'm unable to find any issues that are currently open pertaining to the documentation, specifically.

There probably aren't any but seeing as the project idea involves typescript, html/css then there should be plenty of crossover in technologies with the main app.

Frankly, the project shall majorly involve having the knowledge of Markdown, and how to extract content from the existing documentation, the rest is done by the static site generator itself :slight_smile:
Hence, the knowledge of HTML/CSS and typescript may not be that important.

Markdown and the SSG framework is probably the smaller and easier part of the project.
The bulk of the work is refactoring the docs, the typescript build and the github actions.

We need to understand who we are going to be working with over the entire gsoc period so we require demonstration of skills as well as your general approach to the project and communication with the team.

Agreed. Could you briefly explain the "typescript build"?

Have a look through the project and understand how the current website is built as that is really a prerequisite.

Sure. I'm doing that currently.
I'll get back to you with more stuff and hopefully a PR! :grinning:

1 Like

I think, the implementation of the static site generator should be using typescript.
Like frameworks that allow SSG implementation e.g. Next.js or Gatsby.js or others