Suggestions for documenting AF

[MikeWallaceDev]

Hello everyone, I need some feedback here. I want to gather all of AF's documentation in one place, I'm currently starting to build up the GitHub wiki, but I'm not convinced this is the best tool to do it. We currently have documentation in the code, in readme files, in blog posts, on different websites... It's actually a great start! But it's not as helpful as it could be.

The project has different kinds of documentation and each one might require a different tool:

• User documentation
• Engineering documentation
• Graphical design documentation.
• Marketing documentation

Ideally I would like to limit this to one tool. (Super duper ideally, that tool would be AppFlowy!)

The current top priority is the Engineering documentation so that developers can more quickly understand the code base and be productive. Although I'm happy to hear your ideas about the other types of docs that we have and I will keep it all in mind.

What I want for the Engineering documentation is a central place where a developer can find all of the documentation. Software documentation most usually requires flow charts and diagrams. Ideally these diagrams are interactive and allow to drill down into a component. I'm not opposed at having a central repository that points to external applications in order to create such diagrams.

I know some people like to have the documentation in the code. What are your thoughts on that? How elaborate can this documentation be? What are some good tools?

Any information and opinions on this subject would be greatly appreciated.

Thank you

[polypixeldev]

I don't really know much about documentation in Dart/Rust, but something that would be really nice would be something that generates documentation from the code (from types and doc comments) and compiles it into a website, which could be hosted on GitHub Pages.

[branhillsdesign]

Personally, I'd love to see our documentation get moved to the website and use markdown pages. Could help quite a bit with web traffic and SEO to have docs on the web?

[annieappflowy]

Personally, I'd love to see our documentation get moved to the website and use markdown pages. Could help quite a bit with web traffic and SEO to have docs on the web?

I second to this! Ideally we have all the documentations on our website as the single source of truth and have those docs synced to Github wiki, and vice-versa.

[MikeWallaceDev]

GitHub wiki is a surpringly bad tool.

• The TOC is maintained by hand (although I have seen a tool for this)
• Users can not send a PR for the wiki (its a separate repo from the main repo)
• Editing is difficult (GitHub viewer is finicky)

It's far from ideal.

My point is that if we host documentation on the website, we should just lose the wiki altogether.

[appflowy]

I think the Engineering documentation is really important. It helps people go through the codebase quickly.

1.Documents in one place?
Agreed! It reduces the cost to find the documentation. Besides that, we need to struct the documents and keep updating them. In my experience, the documentation generated from code would be better.

For example:
dartdoc:
https://pub.dev/packages/dartdoc

rustdoc: 
https://rust-lang.github.io/api-guidelines/documentation.html
https://doc.rust-lang.org/rust-by-example/meta/doc.html

2.About the documentation in code
I think some documentation in code is needed because people can get into it quickly. These documentations will include the details of the code logic.

3.Documentation tool.
I recommend the PlantUML. One of my fav tools.

[branhillsdesign]

2.About the documentation in code I think some documentation in code is needed because people can get into it quickly. These documentations will include the details of the code logic.

3.Documentation tool. I recommend the PlantUML. One of my fav tools.

I think for developers, this is great. For anyone else working on the project -- as long as it generates something tangible we could read outside of the codebase -- that's perfect. Honestly, not only is good documentation a smart thing to do to help developers, but it's also a marketing tactic. As such it should be as accessible as possible to all potential marketers, designers, salespeople, and copywriters.

Honestly, it would even be really cool while AppFlowy is in alpha/beta to have the documentation files included with the app download and show up as soon as they open it as a default.

[MikeWallaceDev]

Thank you all for you feedback! It's much appreciated :)

Personally, me, I, moi, moi-même, yo, 我, I'm not a fan of in code documentation. I find that's it's too obtuse, and that it doesn't show a good overall picture of the project. I believe that documentation that comes from the code is only beneficial once you understand the code base but need specific answers. That being said, I am all for it if that is what everyone wants. :)

I also agree that having the documentation on the website is a good idea. Then I want to know exactly which tool we should use to create the documentation?

I think this would be a good plan :

• Have the coders document the code. And keep it up to date with every PR
• Have architectural documentation created by an external tool, written by the system architects
• Have graphical documentation created by an external tool, created by the graphics leads
• Both architectural docs and graphic docs should use the same tools
• Have all three of those documents available on the website.
• Kill the wiki
• Keep just the basic documents in /doc (README, CONTRIBUTING). The others should be on the website.
• No documentation should be duplicated. This is critical. It's hard enough to keep one documentation up to date. Having two is virtually impossible (and it's certainly impossible for our small team)

If you all agree with that, then we just need to decide on which tools to use.

• There are standards for code documentation. We follow those.
  • We add a action to the PR process that generates the documentation.
• Which tool to use for the web
  • A requirement for this tool is that users must be able to submit changes, and have those changes reviewed by the core team.

This is awesome :) I really love working on this project :)

[MikeWallaceDev]

I don't know what to think about the fact that the best tool for this job might be.... Notion.

[annieappflowy]

Thank you all for you feedback! It's much appreciated :)

Personally, me, I, moi, moi-même, yo, 我, I'm not a fan of in code documentation. I find that's it's too obtuse, and that it doesn't show a good overall picture of the project. I believe that documentation that comes from the code is only beneficial once you understand the code base but need specific answers. That being said, I am all for it if that is what everyone wants. :)

I also agree that having the documentation on the website is a good idea. Then I want to know exactly which tool we should use to create the documentation?

I think this would be a good plan :

• Have the coders document the code. And keep it up to date with every PR
• Have architectural documentation created by an external tool, written by the system architects
• Have graphical documentation created by an external tool, created by the graphics leads
• Both architectural docs and graphic docs should use the same tools
• Have all three of those documents available on the website.
• Kill the wiki
• Keep just the basic documents in /doc (README, CONTRIBUTING). The others should be on the website.
• No documentation should be duplicated. This is critical. It's hard enough to keep one documentation up to date. Having two is virtually impossible (and it's certainly impossible for our small team)

If you all agree with that, then we just need to decide on which tools to use.

• There are standards for code documentation. We follow those.

  • We add a action to the PR process that generates the documentation.

• Which tool to use for the web

  • A requirement for this tool is that users must be able to submit changes, and have those changes reviewed by the core team.

This is awesome :) I really love working on this project :)

Hi Mike,

Thanks a lot for listing out our documentation needs. Have you had experience with Gitbook (https://docs.gitbook.com/) ?
I'd imagine that we would need a tool with version control so Gitbook seems to be a better fit than Notion from this perspective: https://docs.gitbook.com/editing-content/editing-pages/change-requests

We're open to other suggestions, and it would be great if it's free for an open-source project like AppFlowy.

Thanks,
Annie

[annieappflowy]

We've decided to adopt GitBook. They have a free community plan for open source projects like AF. Another main decision factor is that they support two-way syncing between GitBook and Github so that people can submit PRs and changes to a Github repo and those merges will be reflected in our GitBook repo automatically, and vice-versa.

I've migrated the contents living in the wiki to https://github.com/AppFlowy-IO/docs
and will do the clean-up work before officially launching it.

[MikeWallaceDev]

Will there be a docs.appflowy.io ?

[annieappflowy]

yes, once we have bandwidth for domains, so we have to bear with the GitBook domain for a while

[MikeWallaceDev]

Wouldn't it just be a redirect to gitbook's servers?