search

foambubble / foam

A personal knowledge management and sharing system for VSCode
https://foambubble.github.io/
Other
15.34k stars 656 forks source link

Improve documentation of vscode extension #355

Closed riccardoferretti closed 2 years ago

riccardoferretti commented 3 years ago
jmg-duarte commented 3 years ago

Regarding the first point I think we should add preview: true since according to the README

This is an early stage project under rapid development. For updates join the Foam community Discord!

jsjoeio commented 3 years ago

I think this all sounds great. I'm not sure if you expect to do all this or if you plan to ask others to pitch in. If the latter, then I would suggest breaking each item into a separate issue and adding more details so others can pick it up.

jsjoeio commented 3 years ago

My only concern with 2 is that I think that may diverge from the structure we suggest for Foam (flat) and the original vision. Up to you though!

jsjoeio commented 3 years ago

I like the sound of 3 - I think the README could definitely use some love.

jsjoeio commented 3 years ago

test the presentation of the newly released extension in the marketplace (e.g. title, icon, readme, links to repo/bugs/..)

Is this something we could automate? Probably not without a lot of effort I'm guessing? I'm just thinking if we added Cypress in someway and then could test to make sure it has the proper title, icon, etc.

riccardoferretti commented 3 years ago

thanks @jmg-duarte and @jsjoeio for your input and ideas!

I'm not sure if you expect to do all this or if you plan to ask others to pitch in

I would definitely love for others to pitch in, I am happy to break things into separate issues, we could tag them all with the "documentation" label and go from there, is that what you were thinking? Regarding the approach, I would like to create a general structure/pattern/template, so that the various pieces can later be added in a more distributed manner while keeping a sort of consistency throughout.

My only concern with 2 is that I think that may diverge from the structure we suggest for Foam (flat) and the original vision. Up to you though!

I don't have a strong opinion in this regard, for me it's about the goal, less about the means. The goal is to navigate the documentation in an easier fashion. If that means having prefixes for files, folders, refactoring of docs, or other approaches, I am open to solutions.

As a broader principle, I think we should support non-flat hierarchies, as it feels too strong of a position to not do so. Flat repos would still be supported of course, so people can choose how to structure their repo.

If the above sounds good, we could use this issue to create the general structure/pattern/template I mentioned above, what do you guys think?

ingalless commented 3 years ago

@riccardoferretti FWIW, the company I work for has found success in the flat prefix-driven approach for documentation. But I also agree the improvement on "hierarchical" notes would be great (for myself in my personal docs too!)

Perhaps Foam's greatest strength could become its ability to support connected notes with hierarchical organisation? 🤔

riccardoferretti commented 3 years ago

@ingalless that's a good data point, thanks!

Let me though clarify an important point: notes in foam are not hierarchical (a note doesn't have a parent), even if they can be stored in a hierarchical file system, in folders and subfolders.

From the POV of foam, all notes are mapped to a flat namespace and connected there.

This is a wide topic, so to avoid scope creep I will leave it here, but I just wanted to clarify what I meant above by hierarchy, as I realize I wasn't clear.

jsjoeio commented 3 years ago

@riccardoferretti

I would definitely love for others to pitch in, I am happy to break things into separate issues, we could tag them all with the "documentation" label and go from there, is that what you were thinking?

Yes, but also adding the "help wanted" and/or the "good first issue". I find that people look for those when they want to contribute so we should add them to be overly explicit that anyone can pick them up. If you do create them, I'm happy to be tagged as a mentor as well (if people need/want that when they pick up the issue).

I don't have a strong opinion in this regard, for me it's about the goal, less about the means. The goal is to navigate the documentation in an easier fashion. If that means having prefixes for files, folders, refactoring of docs, or other approaches, I am open to solutions.

Ah, gotcha. I'm open to solutions too - just wanted to make sure we were considering the original vision.

As a broader principle, I think we should support non-flat hierarchies, as it feels too strong of a position to not do so. Flat repos would still be supported of course, so people can choose how to structure their repo.

Fair point - support for all sounds good to me.

If the above sounds good, we could use this issue to create the general structure/pattern/template I mentioned above, what do you guys think?

That sounds good to me! If you start it, we can comment with thoughts and collaborate here to flesh it out until we're all happy :D

ingalless commented 3 years ago

@riccardoferretti I second @jsjoeio, I'm happy to mentor!

ingalless commented 3 years ago

Another chat I had with @riccardoferretti

Many projects, tools, languages and frameworks have a community driven "awesome list" (example)

Foam could possibly benefit from a similar list to collect all the various tools that contribute to, enhance and support the various foam workflows

riccardoferretti commented 3 years ago

Also, just went to vscode-memo and saw how they organize their documentation, which sounds pretty sensible to me. https://github.com/svsool/vscode-memo/tree/master/help

jsjoeio commented 3 years ago

Also, just went to vscode-memo and saw how they organize their documentation, which sounds pretty sensible to me. https://github.com/svsool/vscode-memo/tree/master/help

That looks sensible to me as well 👍🏼

riccardoferretti commented 3 years ago

At a high level, I feel we have two cases we want to solve for:

I think a challenge would be around coordinating those areas and keep them consistent - thoughts?

jsjoeio commented 3 years ago

Agreed. I think that makes sense, since they'll be in vscode right after they set up their workspace using the foam-template.

For informing new users of features, I think changelog + discord announcements (like you've been doing) seems like the best approach.

As for keeping this consistent, I think we (main committers/contributors) just need to make sure these things happen as new features/prs come in. Thoughts?

riccardoferretti commented 3 years ago

Starting from the end, I agree we should keep an eye on this aspect as part of a PR. We can have a checklist that lives in a PR template and/or issue template with:

I have broken down the three documentation aspects, as I think they each have a role to play (even if sometimes overlapping, and sometimes it's practical to only invest in a subset).

Changelog + Discord is a good practice, but my assumption is that most users are not on Discord, and pay some attention to the changelog

The flow feels a bit heavier, but it's also for the best - I have seen a lot of questions about features or settings that shows that some of our work is hard to discover (and therefore use). What's your take on the above?

jsjoeio commented 3 years ago

I agree it's heavier but probably for the better.

I'm a bit confused on the discovery and documentation (GitHub).

Is one the website and the other GitHub itself, or what do you have in mind?

Also agree about Discord. I am more likely to see new features via the change log rather than Discord.

Overall I like your approach and think this is a move in the right direction. I wonder though if there is perhaps an easier way - write documentation once, find it in three places? Not sure though what that looks like.

riccardoferretti commented 3 years ago

I agree with your single source of truth comment, that to me would live in github: it should always be up to date, should have the most details and examples, and it should be pointed to by all other forms of documentation (e.g. in app discovery and changelog).

Discovery should be called "in app feature discovery". it's the ability of the user to learn about a feature in the context in which it is used. For example, when the user creates its first template, the placeholder text for the template document (pre-filled when the Create Template command is issued) can show some examples of what's possible to the user (e.g. variable substitution, a link to the full documentation, ..). I consider this to be the best type of documentation because it lives in the flow of the user, it's basically unmissable.

Regarding the foam-template documentation, I basically think of it as an app onboarding, where a few notes are created to help the user explore the features of foam when starting from zero. It would include links to the github doc, and some sort of walkthrough (e.g. create your first template, set up your daily notes directory, ...) to help the user get started productively, set herself up, and in the process learn about the core features.

Does that clarify? I am still wrapping my head around it so some aspects might still be unclear

jsjoeio commented 3 years ago

Yes! That all makes a lot more sense now. Thanks for clarifying! 🙌🏼

riccardoferretti commented 3 years ago

I have created #400 to track the task of adding on-boarding to the Foam repo

riccardoferretti commented 3 years ago

big changes to foam template to include some instructions on how to use it. https://github.com/foambubble/foam-template/pull/28