Roshan Chittoor (Jun 07 2019 at 14:02): Roshan Chittoor (Jun 07 2019 at 14:02):Hi Team, I am Roshan working as a Senior Technical Writer. I'm interested in contributing to GSoD. I've seen the project ideas page and here I am to discuss more. Please let me know how I can get started.
Sahibpreet Kaur (Aug 07 2019 at 11:04):Hello everyone, my name is Sahibpreet Kaur and I have been selected in GSoD. I am really grateful for that. I would be working on the project "A Beginner's Guide To BRL-CAD" in the upcoming months. I'll give my best in it.
Also, I have gone through the Checklist and I agree to the acceptance requirements.
Inder Singh (Aug 12 2019 at 07:33):Hi sahib, so glad to see you here :innocent:
Sahibpreet Kaur (Aug 21 2019 at 06:32):@pooh (inder) I am glad to be here. :grinning_face_with_smiling_eyes:
Shankho Boron Ghosh (May 13 2020 at 01:03): Shankho Boron Ghosh (May 13 2020 at 01:03):Hello World.
I am aspiring for Google Summer of Docs 2020. I came across the idea you are mentoring for and would want to know how I can help and make good contributions. I have experience in documentation, though I'm novice in CAD I request your guidance with the next steps of proceeding.
I'm confident that I'll be able to contribute effectively.
Being an avid user of GitHub, this is a suitable project for me. I'm attaching my LinkedIn profile and resume for your reference. Hoping to hear positively from you soon.
Shankho Boron Ghosh (May 13 2020 at 01:22):Season*
Notification Bot (May 13 2020 at 06:44):This topic was moved here from #general > bot command by Sean
Sean (May 13 2020 at 07:11):@Shankho Boron Ghosh I moved your discussion from where you posted to the season of docs stream. You'll want to make sure you're posting messages in the right stream and on the right topic (you can create new topics or continue to use this 'introduction' topic).
As I replied via e-mail, I encourage you to make a contribution relevant to whatever project you intend to propose. The possibilities are endless, but can't really suggest things for you -- that is work expected from successful aspiring technical writer applicants.
Shankho Boron Ghosh (May 13 2020 at 08:27):@Sean Sorry for näivety, I'll go through to @Sahibpreet Kaur's journey last year to see the expectations and the journey through GSoD.
Shankho Boron Ghosh (May 13 2020 at 08:32):Some of my technical writing tasks :
GSoC Proposal : https://drive.google.com/open?id=101IpiAiAMH9ZgBoDULILdnLy9aS1H_aE
University Project (Ongoing) :
Digital Logbook Project Description : https://drive.google.com/open?id=1oneEEhKWQMzfOq7CZwdrDw9hSwmzzyeZa7tDY9ahjHo
Specification Sheet : https://drive.google.com/open?id=1G0CDrQcASDW82MAavaPxhcjBZFRGXuF2KDzRJ0ltK0s
Summer Internship Documentation :
Project Repository : https://github.com/growupboron/Tiger-Detection-Using-ATRW-Dataset
Working Paper : https://github.com/growupboron/Tiger-Detection-Using-ATRW-Dataset/blob/master/doc/Team%2031/AMUR%20TIGER%20DETECTION.pdf
Working Poster : https://github.com/growupboron/Tiger-Detection-Using-ATRW-Dataset/blob/master/doc/Team%2031/Amur%20Tiger%20Detection%20Poster.pdf
SDR Guide (for fellow students) : https://drive.google.com/open?id=1F0iWgF1hKrbLEW7nqdPK_zSlmh_AkcK6j3x_D2R81IM
ROS Guide (for fellow students) : https://docs.google.com/document/d/1MPgMCdI-vpKmrnv5z6LEiavLzmBbK3_nbB18Z5HDcNk/edit?usp=sharing
Multiple Hackathon Pitching Presentations : https://drive.google.com/open?id=1OYFOQsNCt8C-z9GSXdx23hF5DpqGAsb9
Shankho Boron Ghosh (May 13 2020 at 08:33):^I am hoping for constructive criticism and how I can develop more on this. Thanks.
Arzoo Prajapati (May 13 2020 at 10:49):Hello everyone,
I am Arzoo, currently pursuing Computer Science and Engineering, Dual Degree (Bachelors + Masters) at the National Institute of Technology, Hamirpur.
I am looking forward to Google Season of Docs 2020. I am interested in working on 'Upgrade doc infrastructure'. I have done this type of project before as well for Point Cloud Library organization. I have also experience in technical writing. I have done an internship at Wedabout, Gurugram where I worked as a technical writer.
My GitHub handle: arzoo14
My project with Point Cloud Library: Project
I am very well aware of readthedocs, Sphinx, rst, webhooks, Doxygen, Docbook XML, AsciiDoc, MD, Docusaurus.
Please have a look at that project. I have made their documentation in readthedocs as asked by the organization, but I am also aware of other documentation generator sites.
Please guide me for proceeding ahead over this project idea.
Looking forward to hearing from you.
Arzoo Prajapati (May 13 2020 at 11:02):Project link : https://github.com/arzoo14/PCL_coding_work_2
Sean (May 13 2020 at 15:43):Thank you for sharing @Shankho Boron Ghosh
Sean (May 13 2020 at 15:43):Are you presently participating in GSoC, or have you participated before?
Notification Bot (May 13 2020 at 15:46):This topic was moved here from #announce > Google Season of Docs by Sean
Shankho Boron Ghosh (May 13 2020 at 15:47):No, I am not and haven't. I did try this year, but my project got dropped due to the org not able to ship the necessary hardware in view of COVID.
Sean (May 13 2020 at 15:47):Hi @Arzoo Prajapati. I moved your post from #announce to the stream more appropriate for GSoD.
Sean (May 13 2020 at 15:50):@Arzoo Prajapati I see you published that rtd site about a month ago -- what was it for? what are the PCL guys going to do with it?
Please tell more about your internship at Wedabout too.
Arzoo Prajapati (May 13 2020 at 16:06):Hi Sean
Yes, it was their GSoC project but in the end they guys told that it is more of a GSoD project. And unfortunately, PCL organization didn't get selected for GSoD.
Arzoo Prajapati (May 13 2020 at 16:08):https://github.com/PointCloudLibrary/pcl/wiki/PCL-GSoc-Ideas#project-maintenance-proj here you can find their idea.
Arzoo Prajapati (May 13 2020 at 16:10):Since, this project idea is also similar to that one and I'm preety experienced regarding this project. So, I'm thinking to do this project for BRL-CAD organization.
Arzoo Prajapati (May 13 2020 at 16:12):In my internship at wedabout, I worked as a technical writer who tested the website and sent the drawbacks to the company. As well as, give them all the necessary feedbacks and new outcomings as an user in the documented form.
Arzoo Prajapati (May 13 2020 at 16:17):Please find my GSoC proposal for Update outdated website of PCL here - https://docs.google.com/document/d/1aq1eThzQXSctWKrVCDHCo8aA1Lkz4Zyt1XN7bmLz2lQ/edit
Arzoo Prajapati (May 15 2020 at 17:31):gentle ping @Sean
Sam Robbins (May 18 2020 at 18:54):Hi All! I'm interested in participating in Google Season of Docs, particularly updating the documentation infrastructure. I'm a University Computer Science Student and just finished a year-long project that involved writing up documentation using Docusaurus, you can check it out here https://se-docs.netlify.app/ .
Sean (May 18 2020 at 19:00):@Arzoo Prajapati yes? sorry if I missed a question..
Sean (May 18 2020 at 19:03):@Arzoo Prajapati the only thing I'll note is that GSoD is very different in its goals from GSoC, so a proposal to GSoC is not particularly relevant other than perhaps in some overarching objectives. For GSoD, you want to really 1) emphasize and describe your technical writing background and 2) describe your proposed project via rough drafts. Your proposal should exemplify your technical writing expertise.
Sean (May 18 2020 at 19:04):Hi @Sam Robbins and (again) welcome. Thanks for sharing the link to the docusaurus project. What can you tell me about it?
Sam Robbins (May 18 2020 at 19:07):We created a stock take system for a food bank, which we were to pass over the code once finished, so this documentation covers details for both technical and non technical users. I've found docusaurus very easy to use, and provides a good range of features to communicate everything you need to in documentation. The one criticism is that the user interface is fairly rigidly set in place, so other solutions are better in this regard.
Sean (May 18 2020 at 20:27):@Sam Robbins the biggest limitation I think I've come across is that docusaurus doesn't seem ready to produce agglomerated PDF output.
Sam Robbins (May 18 2020 at 20:28):Yeah I had that exact problem and had to generate two sets of docs, one with sphinx and one with docusaurus. If PDF output is important I'm also comfortable using ReadTheDocs to generate both web and pdf simultaneously
Sean (May 18 2020 at 20:29):Does RTD work offline or self-hosted?
Sam Robbins (May 18 2020 at 20:37):Underlying RTD is Sphinx, which yeah you can use to generate a set of HTML pages to use offline
Rishabh Bakshi (May 18 2020 at 20:40):Hi, everyone. I'm a mechanical engineering undergrad student from Indian Institute of Technology Roorkee. I don't really have much experience of open source or GitHub but am quite comfortable with CAD softwares. I have a little experience of technical writing as I have written a few work reports, 'how to'-guides for a few software packages (which are supposed to be for my juniors), project reports etc. I'm a part of the FSAE team of our campus and have done most of my technical writing work for the team.
I came to know about BRLCAD and the ideology behind it very recently. Having a powerful CAD software can really give any engineer superpowers. I would really love to contribute BRLCAD in any way I could.
I can't really contribute to some of the projects, as they're very irrelevant to my field. But I'd really love to contribute to the 'Write a "BRL-CAD Primitives" manual' project. Also, the 'Organize all existing user docs' project seems very relevant to me, as having a little experience with struggling to learn how to use CAD softwares would help me in being a bit more emphatic to the needs of the 'rookies'.
I just wanted to know, am I wrong to think that I can contribute to the projects of such scale without having much experience with open source softwares before?
Sean (May 18 2020 at 21:51):@Sam Robbins I'd rather stay away from sphinx if we can, if only due to the maintenance overhead and complexity compared to alternative. We have a LOT of docs, so whatever solution we put in place needs to be complete and as simple as possible.
Sean (May 18 2020 at 21:52):ideally integrating with Github so edits can get submitted as reviewable requests
Sean (May 18 2020 at 21:52):from the research I've done, it looks like Antora or a custom static site (e.g., hugo or jekyll) can work, but both would require customization
Sean (May 18 2020 at 21:53):@Sam Robbins I'll probably ask again, but can you share more on your technical writing background?
Sean (May 18 2020 at 21:53):welcome @Rishabh Bakshi ! Thank you for the introduction.
Sam Robbins (May 18 2020 at 21:57):Sadly I don't have as much experience in technical writing as I would like. I did write a lot of that documentation website I shared and that's most of what I've done
Sean (May 19 2020 at 02:03):@Rishabh Bakshi Just to follow up, GSoD does not require any prior experience with BRL-CAD. It is expected that applicants will have some relevant technical writing experience. GSoD is structured to encourage those interested in or already working as a professional technical writer. We of course also have an interest in anyone that can help us with our documentation projects, everything else being equal.
Sean (May 19 2020 at 02:06):@Sam Robbins We still encourage you to apply. If applicants were graded (they're not, it's more complicated) then technical writing background would probably be something like 50% while someone able to improve the state of technical writing tooling and infrastructure might account for the other 50%.
Rishabh Bakshi (May 19 2020 at 15:51):@Sean I was going through some documentation and realised that I can start contributing to the documentation straight away. I will try contributing to that to see if the open source work fits me. And regarding the prior experience, am I supposed to post my previous work here or attach it with the proposal?
Sean (May 19 2020 at 15:57):@Rishabh Bakshi you can do either. If you post it publicly, then you will get back feedback publicly before the deadline and have an opportunity to change your proposal/portfolio. If you attach it with the proposal, it will be taken into consideration during review along with all other proposals.
Arzoo Prajapati (May 21 2020 at 17:14):Sean said:
from the research I've done, it looks like Antora or a custom static site (e.g., hugo or jekyll) can work, but both would require customization
@Sean So, are we moving from Docusaurus to Hugo or Jekyll? I've one more idea in my mind- MkDocs.
Arzoo Prajapati (May 21 2020 at 17:15):Sean said:
ideally integrating with Github so edits can get submitted as reviewable requests
This feature is also there in readthedocs. It can be implemented with the help of webhooks.
Sam Robbins (May 21 2020 at 17:16):If a PDF is required then docusaurus won't be able to do this sadly
Arzoo Prajapati (May 21 2020 at 17:17):But readthedocs support pdfs also :)
Sam Robbins (May 21 2020 at 17:18):Yeah personally a ReadTheDocs solution seems best, but Sean seemed against using sphinx
Sean (May 21 2020 at 21:15):I'm not familiar with completely how they work -- does ReadTheDocs support self-hosting and offline? We want to host the docs on our own site (perhaps on our github pages), not on a readthedocs site.
My biggest complaint about sphinx is that they use .rst
I think asciidoc or markdown will be more appropriate for our docs (different merits and downsides to both, but overall better fit than restructuredtext).
Arzoo Prajapati (May 23 2020 at 11:24):Regarding github pages, I would suggest markdown will be best.
Arzoo Prajapati (May 23 2020 at 11:28):@Sean So, I would like to know is Github Pages with Markdown format is perfectly suitable for our site? If so, then I think I should start working on proposal and proof of concept. Looking forward to hearing from you. :)
Sam Robbins (May 23 2020 at 15:08):@Sean can I just check, is having a PDF a requirement or is it just that it should be available offline?
Sean (May 23 2020 at 15:29):@Arzoo Prajapati markdown is great for casual writing but kind of terrible for advanced technical output and advanced layout, which we have a LOT of. We would be dumbing down our documentation significantly in some places. Not opposed to it, but it wouldn't be my first choice for that reason.
Sean (May 23 2020 at 15:30):Asciidoc seems to be a nice balance between simplicity and supporting advanced structures (and has a proper schema/format that can be validated).
Sean (May 23 2020 at 15:34):@Sam Robbins that's a huge "it depends" I think. having a PDF is really nice for users that want a table-side reference, which is a common working pattern and desired by BRL-CAD users.
If we go with something that can't be made into a PDF, then it likely means it can't be easily printed out on paper (e.g., lot of web browser pages). So I think "must be able to print at least each book chapter, manual page, or quick reference with one action" is the requirement, however it is achieved.
Sam Robbins (May 23 2020 at 15:34):Yeah that makes sense
Sean (May 23 2020 at 15:38):That doesn't preclude browser-only systems, but it would have implications on how documents are presented and structured, like whether a whole chapter with lots of sections has a means to be displayed all at once or not, and how much of the website decoration can be made to disappear when printing (nobody wants to see headers and menu bars in a printed doc).
Arzoo Prajapati (May 23 2020 at 16:40):@Sean Asciidoc is good one for advanced documentation. I have one more suggestion which supports advanced layout- WackoWiki
Ronnie Gandhi (May 25 2020 at 08:12):Hello everyone,
I am Ronnie Gandhi, a Computer Science undergrad student from IIT Roorkee. I am currently enrolled in my pre-final year.
I have looked through your project ideas page on GSoD. I am interested in working on the project "Organize and publish developer docs". I have used Doxygen multiple times while working on academic projects for building small documents. I have done GSoC last year and this year as well I am selected a student under CGAL where I am working with C++ over their libraries which also help me become good at reading other's codes.
I am ready to learn any specific new thing needed for this project
Regards,
Ronnie
Rajvir Singh (May 26 2020 at 20:16):Hi,
I am Rajvir Singh, a Computer Science student. I have worked with various web development languages. As a blogger, I like to share my knowledge with people. I would love to work with your organization for the Google Season of Docs.
Kindly Let me know, where can I get started.
You may have a look at my blog by this link - https://medium.com/@rsaggu99.
Looking forward to working with you.
Regards,
Rajvir Singh
Sam Robbins (May 27 2020 at 18:52):I was just looking at the converting unmanaged to managed idea, do you have some examples of the content to be converted?
Sean (May 31 2020 at 06:06):Hi @Ronnie Gandhi @Rajvir Singh and @Sam Robbins , welcome! I look forward to seeing a writing portfolio. Sam, yes, there are several examples on our website under Docs. Look for pdfs in particular for a couple good examples.
Sean (Jul 10 2020 at 02:31):Thank you to everyone that submitted at an application to work on BRL-CAD under the Season of Docs. I'll be in touch over the next few days if there are any questions or follow-up concerns. Feel free to reach out to me if you have any questions yourself. Thanks again!
Sean (Sep 14 2020 at 17:44):@Rohan Rathi Please introduce yourself.
Rohan Rathi (Sep 15 2020 at 17:57):Hi everyone my name is Rohan Rathi, I'm a software engineer working with Uber and a passionate open source ninja building awesome 3D creation suites for organisations like Blender 3D. I'll contributing to BRL-CAD to improve it documentation and hopefully will collaborate with all the awesome devs here :)
Shubham Rathore (Sep 16 2020 at 03:47):Welcome @Rohan Rathi to the org !
Rohan Rathi (Sep 18 2020 at 17:18):Hello Shubham! I suppose I can work closely with you to get upto speed?
Rohan Rathi (Sep 18 2020 at 17:22):I've created a (very rough) Google doc for now on what goals I plan on achieving in this project, along with some additional scopes I plan on adding later, would appreciate if you could review it and we could get the ball rolling https://docs.google.com/document/d/19ujCMDxIWuQIxV9myFX_6PmQ7fyIS6ldzFgW0knIpyk/edit?usp=sharing
Sean (Sep 18 2020 at 17:24):@Rohan Rathi oh, thanks for posting a draft! That's a good start. Would you like comments here or in the doc?
Rohan Rathi (Sep 18 2020 at 17:26):I think discussion here is better, maybe the Google doc can be cluttered, you have edit access as well so you can add any direct comments at the end
Sean (Sep 18 2020 at 17:31):okay, great!
Sean (Sep 18 2020 at 17:31):are you familiar with breadth-first vs depth-first approaches to development?
Sean (Sep 18 2020 at 17:35):if you are, it'd be great it we think about approaching the project in a depth-first manner, as we're in uncharted territory. For example, we're giving Antora a try, but it's not yet proven itself. So before converting all our docs to Asciidoc, I would suggest we convert just a handful of docs, like maybe 1 first, take it to completion (fully published, repos in place, website generated, etc) .. and then maybe work on 5 more of different types of docs, and then we re-evaluate the plan and see if it's going in a direction we like.
Sean (Sep 18 2020 at 17:36):which in terms of a docs plan, means not converting all our docs to ascii doc - that could take weeks in itself. instead, maybe just identify the first 5-6 docs to convert. A simple doc, a manual page, a wiki page, one tutorial lesson, and maybe an article, for example.
Sean (Sep 18 2020 at 17:38):doxygen docs can be phase 2, and it's okay if we never get to phase 2. the mess that needs to be contained and organized most are the docs on the wiki and the docs in the doc/ subdir. Unifying them into their own repository one at a time (again, just starting with 1-5 of them) that will later become a git submodule checkout replacing doc/
Rohan Rathi (Sep 18 2020 at 17:46):I understand your point and it's entirely valid, I've read good stuff about Antora so far. I'm particularly concerned about translations if we have any as we move to a new build engine.
Sean (Sep 18 2020 at 17:58):Good point, I suggest including our About page in your initial 5-6 then - it has a half dozen translations.
Sean (Sep 18 2020 at 17:59):it could be the 'article' I mentioned
Sean (Sep 18 2020 at 18:00):it's in doc/docbook/articles/about.xml
Sean (Sep 18 2020 at 18:00):translations in the hy, ru, and it subdirs
Rohan Rathi (Sep 18 2020 at 18:16):Awesome, let me learn more about Antora and other doc engines for now and then I'll move these pages to asciidoc
Rohan Rathi (Sep 18 2020 at 18:17):From what I've read fedora had also migrated their docs to Antora in 2018
Sean (Sep 22 2020 at 20:59):@Rohan Rathi when will you be able to update the doc plan? you should do that first so we're on the same page as to what's being worked on. Please do post a status update here whenever you work on anything, so we can interact better / more frequently. Four day gaps aren't sustainable...
Sean (Sep 23 2020 at 06:14):@Rohan Rathi ...?
Rohan Rathi (Sep 23 2020 at 06:56):My bad, updating the doc
Last updated: Jan 10 2025 at 00:48 UTC