Foam: Call for Documentation

[jmg-duarte]

Hello everyone!

As any healthy open-source project, I think Foam requires more love regarding documentation.
From the get-go both to users and developer to the advanced scenarios, documentation is an integral part of any good project.

We ought to do the same and so I propose we look towards increasing documentation coverage in Foam.
A simple way to start is: whenever we write code, whether completely new, or a small bugfix, we should try to add/improve the documentation of the code we touch.

For example, I recently changed the way the bootstrap function loads the filenames to consider and I added documentation to my code:
https://github.com/foambubble/foam/blob/90f869e8d0d0c1df7f84d4980efefe51815d712c/packages/foam-vscode/src/extension.ts#L71-L93

However, I also added a simple utility function which was undocumented, while simple, I should have documented both functions:
https://github.com/foambubble/foam/blob/90f869e8d0d0c1df7f84d4980efefe51815d712c/packages/foam-vscode/src/extension.ts#L49-L53

That is not to say that every piece of code entering the codebase needs to be documented, but rather, it should be.

This will lower the entry barrier for newcomers, help existing developers navigating new parts of the codebase and debugging older parts.

[riccardoferretti]

@jmg-duarte I agree with the spirit of the request, how about updating the docs/contribution-guide.md file?
This sounds like the best way to communicate this type of principle.
Thoughts?

[jmg-duarte]

Sounds like a plan to me!
I think https://github.com/foambubble/foam/blob/master/docs/contributing.md should be moved to the main folder so people can get to the file in 2 clicks and without searching.

I can write the guide however before picking it up, what do you think about dividing in the following sections:

• Getting Up to Speed
  
  
  
  • Principles
  
  
  • Code of Conduct
  
  
• Diving In
  
  
  
  • Foam Architecture
  
  
  • Roadmap
  
  
  • Check out the issues
  
  
  • Use Foam and help us improve with feedback
  
  
• Contributing

[riccardoferretti]

quickly scanning the repo, I see 3 contributing docs:

• docs/contributing.md
• .github/CONTRIBUTING.md
• docs/contribution-guide.md

I agree with consolidating those (or at least their responsibilities) and having the main one at the root.

The structure sounds good, let's move forward with it.
There are docs around some of those aspects, I would update them where you see the need, and keep the main contribution file as an entry point with links to those - is that what you were thinking?

[jmg-duarte]

Yes, precisely!

[riccardoferretti]

I will close this issue as I believe the merged branch addresses the points here, feel free to comment/reopen if I am missing something