Comments on the Gaphas documentation

[janettech]

Hello Dan,

As discussed earlier, here are my review comments on Gaphas docs. I hope you find them useful.
If you find anything that is not clear, please do ask. Also, ignore if I did any mistakes.

The latter part of my document you will find just the grammatical correction on the content. I hope you find the corrections.

Thanks!
Janet
Gaphas.docx

[danyeaw]

Thanks so much for all of your time an effort helping us improve our README, that is awesome ❤️

The way GitHub gives credit for things is based on commits you make through a Pull Request. It looks like you have made some commits to projects in the past, would you be interested in submitting a PR with your proposed changes? If that would interest you, I would be glad to help you accomplish that.

I thought I would also respond to your comments directly in the issue to make the discussion more open, I hope that is OK for you.

1. Since Gaphor is built on GTK+ and Cairo, (Capitalize Cairo as you have done in Gaphas Documentation).

Do you have a Glossary to what GTK+ and Cairo are?
Or maybe put hyperlinks on these.

I think adding a hyperlink is a great idea. Also GTK dropped the + from their name, so we should fix that as well.

2. However, there wasn't a project that abstracted these technologies to easily create a diagramming tool.

Explain here—What you are trying to achieve using Gaphas or this is the reason why Gaphas was created…

Yes, maybe we could explain this better. Gaphas was created as a library to allow others to create a diagramming tool using GTK and Cairo.

3. Here is how it works:

Before putting the above line, maybe could explain what Canvas is?

Yes, great idea!

4. https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/

This link has a detailed explanation to create virtual environments in different OS. I am a newbie to Python and I use Mac.

Good point, maybe we could use a friendlier link like from the virtualenv docs or from the Hitchhiker's Guide to Python.

(Installing Gaphas on MacOS was not straightforward and some libraries had to be installed and took a while to get it all running. (pkg-config, cairo, libffi, gobject-introspection). The thing about documentation is to help the user with all the needed information for smoother installation).

We did include installation instruction in the Gaphor README for macOS, I agree that we missed that and we should add it.

How about steps to uninstall Gaphas?

I never really thought about that before. I guess that would be useful 👍

[janettech]

Hello danyeaw,

That is awesome that my comments helped you. I am not aware of the GitHub credit. Yes, definitely I would like to raise a PR. Let me know how to proceed.

Thanks!

[danyeaw]

I think Digital Ocean's Pull Request Tutorial is well done, and you'll appreciate that it is written by a technical writer. 😄

General steps:

1. Fork the repository (this creates your own copy that you control)
2. Clone your fork to your computer with git clone https://github.com/janettech/gaphas.git
3. Create a new branch to edit called update-readme or similar using git checkout -b update-readme
4. Use a dedicated Markdown Editor like Marktext or Typora, or a code editor like VSCode to edit the README.md. If you already have an editor that you are comfortable with, use that one. I was only providing suggestions in case you didn't have one setup already. 👍
5. Commit your changes with a commit message using git commit -m "Cleanup README for spelling and grammer"
6. Push your changes to your forked repository using git push
7. Create a Pull Request

If you get stuck on any of these steps, I would be glad to help you either on Gitter or I can even setup a video conference with you if needed.

[janettech]

Hello Dan,

I have done until step 6.
Message shows as "Everything up to date".
Now after this I don't see the local repo changes of README in the Github repo.

In order to do a PR, I should first see the change in README. I am not able to see my changes at all. Please let me know what I am doing wrong or missing?
Thanks!

[janettech]

Hello Dan,

I was able to see the changes and I have submitted the PR. Please review.
Thanks!

[danyeaw]

Closed by #48. 👍