You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The current README which hosts instructions on how to create documentation with docfx is out of date and a little short on detail. It would also be good to standardize best practices for documentation, which currently is spread mainly through discussions with package developers/documentation writers. A previous attempt was made at #82, and as part of the feedback for that PR, it was brought up that it might be better to package this as an article. This would also serve as a good base for discussion during the documentation session for the upcoming Bonsai Developer Conference.
Proposed solution
While I was working on it, I found that it was getting too long and thought there was enough content to split it into two articles. Thus I propose making the following changes:
Documentation with docfx- This would cover repository and docs folder organization, installing docfx and docfx configuration, publishing to github pages, and troubleshooting tips
Documentation style guide - This would cover article organization, constructing the table of contents, using individual operator articles and the overwrite function, bonsai workflow image export and containers, standard formatting for operators and other common Bonsai content.
README.md - Trim it to just the basics for people to get started with contribution, with links to the articles on docfx and documentation style guide.
Additional issues to consider
Article Location - currently the articles does not fit nicely into the existing article categories, but Extending Bonsai is the closest since there is also a Create a Package article. I think creating a new section for Custom Package Development or even a Bonsai Developers subsection of the website would be a better fit (as it is not technically a manual article for normal Bonsai Users). There might not be enough content to go with the later option, but I think the package development articles also need to be expanded (unfortunately I have zero experience with that)
The text was updated successfully, but these errors were encountered:
Motivation
The current README which hosts instructions on how to create documentation with docfx is out of date and a little short on detail. It would also be good to standardize best practices for documentation, which currently is spread mainly through discussions with package developers/documentation writers. A previous attempt was made at #82, and as part of the feedback for that PR, it was brought up that it might be better to package this as an article. This would also serve as a good base for discussion during the documentation session for the upcoming Bonsai Developer Conference.
Proposed solution
While I was working on it, I found that it was getting too long and thought there was enough content to split it into two articles. Thus I propose making the following changes:
Documentation with docfx- This would cover repository and docs folder organization, installing docfx and docfx configuration, publishing to github pages, and troubleshooting tips
Documentation style guide - This would cover article organization, constructing the table of contents, using individual operator articles and the overwrite function, bonsai workflow image export and containers, standard formatting for operators and other common Bonsai content.
README.md - Trim it to just the basics for people to get started with contribution, with links to the articles on docfx and documentation style guide.
Additional issues to consider
Extending Bonsai
is the closest since there is also aCreate a Package
article. I think creating a new section forCustom Package Development
or even aBonsai Developers
subsection of the website would be a better fit (as it is not technically a manual article for normal Bonsai Users). There might not be enough content to go with the later option, but I think the package development articles also need to be expanded (unfortunately I have zero experience with that)The text was updated successfully, but these errors were encountered: